> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/components/tag.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt.

# Tag 标签

标记内容的分类或状态。

## 基础用法


defaultprimarysuccessinfowarningerror

已发布已完成可移除大标签

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tag/basic.tsx"
import { Flex, Space, Tag } from '@ifhover/leaf-ui';

import { Check } from 'lucide-react';

export function TagBasic() {
  return (
    <Space direction="vertical" align="stretch">
      <Flex gap="md" align="center" wrap justify="center">
        {(['default', 'primary', 'success', 'info', 'warning', 'error'] as const).map((color) => (
          <Tag key={color} color={color}>
            {color}
          </Tag>
        ))}
      </Flex>
      <Flex gap="md" align="center" wrap justify="center">
        <Tag color="primary" variant="solid">
          已发布
        </Tag>
        <Tag color="success" icon={<Check />}>
          已完成
        </Tag>
        <Tag color="#7654c6" closable>
          可移除
        </Tag>
        <Tag size="lg" color="primary">
          大标签
        </Tag>
      </Flex>
    </Space>
  );
}
```

展开代码

## Tag API

| 属性         | 类型                                                                                | 默认值         | 说明               |
| ---------- | --------------------------------------------------------------------------------- | ----------- | ---------------- |
| `children` | `ReactNode`                                                                       | —           | 标签内容             |
| `color`    | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error' \| 'info' \| string` | `'default'` | 语义颜色或自定义颜色       |
| `variant`  | `'soft' \| 'solid'`                                                               | `'soft'`    | 浅底或实色形态，均为无边框小圆角 |
| `size`     | `'sm' \| 'md' \| 'lg'`                                                            | `'md'`      | 标签尺寸             |
| `icon`     | `ReactNode`                                                                       | —           | 前置图标             |
| `closable` | `boolean`                                                                         | `false`     | 展示关闭按钮           |
| `onClose`  | `(event: MouseEvent<HTMLButtonElement>) => void`                                  | —           | 关闭时触发            |

## 类型

定义组件属性或组装列表时可导入相关类型。

```ts
import type { TagProps, CheckableTagProps, TagGroupProps, TagOption } from '@ifhover/leaf-ui';
```

## 使用说明

标签使用无边框的小圆角，仅提供浅底与实色形态。圆角跟随区域主题，也可通过 `ConfigProvider` 的 `theme.components.Tag.borderRadius` 单独设置。

调用 event.preventDefault() 可阻止默认移除。在动态列表中，也可以通过 onClose 更新应用状态并移除对应项。

## CheckableTagProps API

| 属性               | 类型                           | 默认值     | 说明      |
| ---------------- | ---------------------------- | ------- | ------- |
| `checked`        | `boolean`                    | —       | 受控勾选状态  |
| `defaultChecked` | `boolean`                    | `false` | 初始勾选状态  |
| `onChange`       | `(checked: boolean) => void` | —       | 值变化回调   |
| `size`           | `'sm' \| 'md' \| 'lg'`       | `'md'`  | 尺寸或间距预设 |

## TagGroupProps API

| 属性             | 类型                                       | 默认值    | 说明                  |
| -------------- | ---------------------------------------- | ------ | ------------------- |
| `options`      | [`readonly TagOption[]`](#tagoption-api) | 必填     | 可用选项                |
| `value`        | `readonly string[]`                      | —      | 受控值                 |
| `defaultValue` | `readonly string[]`                      | `[]`   | 初始值；非受控表单 reset 时恢复 |
| `onChange`     | `(values: string[]) => void`             | —      | 值变化回调               |
| `disabled`     | `boolean`                                | —      | 禁止交互                |
| `size`         | `'sm' \| 'md' \| 'lg'`                   | `'md'` | 尺寸或间距预设             |
| `name`         | `string`                                 | —      | 表单字段名称              |
| `form`         | `string`                                 | —      | 关联表单 ID             |
| `required`     | `boolean`                                | —      | 表单必填验证              |

## TagOption API

| 属性         | 类型          | 默认值 | 说明   |
| ---------- | ----------- | --- | ---- |
| `value`    | `string`    | 必填  | 受控值  |
| `label`    | `ReactNode` | 必填  | 显示内容 |
| `disabled` | `boolean`   | —   | 禁止交互 |