---
title: Chip 标签
description: 用于显示标签、状态与分类的小型信息徽章
links:
  source: chip/chip.tsx
  styles: chip.css
  storybook: Components/Data Display/Chip
  figma: true
---

## 用法

```tsx
import { Chip } from '@heroui/react';
```

<ComponentPreview
  name="chip-basic"
/>

## 组件结构

> 纯文本子节点会自动包裹在 `<Chip.Label>` 中。

```tsx
<Chip>
  Label text
</Chip>
```

## 示例

### 变体

<ComponentPreview
  name="chip-variants"
/>

### 状态类型

<ComponentPreview
  name="chip-statuses"
/>

### 带图标

<ComponentPreview
  name="chip-with-icon"
/>

## 自定义样式

### Tailwind CSS

<ComponentPreview name="chip-custom-styles" />

### 全局 CSS

可使用 `@layer components` 指令自定义 Chip 组件类。
[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

```css
@layer components {
  .chip {
    @apply rounded-full text-xs;
  }

  .chip__label {
    @apply font-medium;
  }

  .chip--accent {
    @apply border-accent/20;
  }

  .chip--accent .chip__label {
    @apply text-accent;
  }
}
```

## 样式参考

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

Chip 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/chip.css)）：

#### 基础类 [!toc]
- `.chip` - 基础标签容器样式
- `.chip__label` - 标签文本 slot 样式

#### 颜色类 [!toc]
- `.chip--accent` - 强调色变体
- `.chip--danger` - 危险色变体
- `.chip--default` - 默认色变体
- `.chip--success` - 成功色变体
- `.chip--warning` - 警告色变体

#### 变体类 [!toc]
- `.chip--primary` - 填充背景的主变体
- `.chip--secondary` - 带边框的次变体
- `.chip--tertiary` - 透明背景的三级变体
- `.chip--soft` - 浅色背景的 soft 变体

#### 尺寸类 [!toc]
- `.chip--sm` - 小尺寸
- `.chip--md` - 中尺寸（默认）
- `.chip--lg` - 大尺寸

#### 复合变体类 [!toc]

Chip 支持组合变体与颜色类（如 `.chip--secondary.chip--accent`）。以下组合有默认样式：

**Primary Variants:**
- `.chip--primary.chip--accent` - 填充背景的 primary accent 组合
- `.chip--primary.chip--success` - 填充背景的 primary success 组合
- `.chip--primary.chip--warning` - 填充背景的 primary warning 组合
- `.chip--primary.chip--danger` - 填充背景的 primary danger 组合

**Soft Variants:**
- `.chip--accent.chip--soft` - 浅色背景的 soft accent 组合
- `.chip--success.chip--soft` - 浅色背景的 soft success 组合
- `.chip--warning.chip--soft` - 浅色背景的 soft warning 组合
- `.chip--danger.chip--soft` - 浅色背景的 soft danger 组合

**Note:** 可使用 CSS 中的 `@layer components` 指令为任意变体-颜色组合（如 `.chip--secondary.chip--accent`、`.chip--tertiary.chip--success`）应用自定义样式。

## API 参考

### Chip

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `children` | `React.ReactNode` | - | 标签内显示的内容 |
| `className` | `string` | - | 根元素附加 CSS 类 |
| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | 标签颜色变体 |
| `variant` | `"primary" \| "secondary" \| "tertiary" \| "soft"` | `"secondary"` | 视觉样式变体 |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 标签尺寸 |

### Chip.Label

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `children` | `React.ReactNode` | - | 标签文本内容 |
| `className` | `string` | - | 标签 slot 附加 CSS 类 |

## 相关组件

<RelatedComponents component="chip" />