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

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

# Tag 标签

标记内容的分类或状态。


## 基础用法

使用 Tag 为内容添加简短的分类或状态标签。


进行中

basic.tsx

复制代码

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

export function TagBasic() {
  return <Tag>进行中</Tag>;
}
```

展开代码


## 示例

### 颜色

默认标签使用灰色背景和黑色文字；示例展示全部内置颜色和自定义颜色。


默认成功信息警告危险自定义

colors.tsx

复制代码

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

export function TagColors() {
  return (
    <Flex gap="sm" wrap>
      <Tag>默认</Tag>
      <Tag color="success">成功</Tag>
      <Tag color="info">信息</Tag>
      <Tag color="warning">警告</Tag>
      <Tag color="danger">危险</Tag>
      <Tag color="#722ed1">自定义</Tag>
    </Flex>
  );
}
```

展开代码

### 外观

通过 `variant` 选择 `soft`（浅色背景配颜色文字）或 `solid`（颜色背景配白色文字）。示例展示全部内置颜色和自定义颜色。


soft默认成功信息警告危险自定义

solid默认成功信息警告危险自定义

variants.tsx

复制代码

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

export function TagVariants() {
  return (
    <Flex direction="column" gap="sm" align="start">
      <Flex gap="sm" align="center" wrap>
        <Text tone="muted">soft</Text>
        <Tag>默认</Tag>
        <Tag color="success">成功</Tag>
        <Tag color="info">信息</Tag>
        <Tag color="warning">警告</Tag>
        <Tag color="danger">危险</Tag>
        <Tag color="#722ed1">自定义</Tag>
      </Flex>
      <Flex gap="sm" align="center" wrap>
        <Text tone="muted">solid</Text>
        <Tag variant="solid">默认</Tag>
        <Tag color="success" variant="solid">
          成功
        </Tag>
        <Tag color="info" variant="solid">
          信息
        </Tag>
        <Tag color="warning" variant="solid">
          警告
        </Tag>
        <Tag color="danger" variant="solid">
          危险
        </Tag>
        <Tag color="#722ed1" variant="solid">
          自定义
        </Tag>
      </Flex>
    </Flex>
  );
}
```

展开代码

### 图标

图标示例展示 `soft` 与 `solid` 外观，并覆盖全部内置颜色和自定义颜色。标签不再提供内置圆点。


soft默认成功信息警告危险自定义

solid默认成功信息警告危险自定义

icons.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tag/icons.tsx"
import { Flex, Tag, Text } from '@ifhover/leaf-ui';
import { Check, CircleAlert, CircleX, Info, Sparkles, Tag as TagIcon } from 'lucide-react';

export function TagIcons() {
  return (
    <Flex direction="column" gap="sm" align="start">
      <Flex gap="sm" align="center" wrap>
        <Text tone="muted">soft</Text>
        <Tag icon={<TagIcon />}>默认</Tag>
        <Tag color="success" icon={<Check />}>
          成功
        </Tag>
        <Tag color="info" icon={<Info />}>
          信息
        </Tag>
        <Tag color="warning" icon={<CircleAlert />}>
          警告
        </Tag>
        <Tag color="danger" icon={<CircleX />}>
          危险
        </Tag>
        <Tag color="#722ed1" icon={<Sparkles />}>
          自定义
        </Tag>
      </Flex>
      <Flex gap="sm" align="center" wrap>
        <Text tone="muted">solid</Text>
        <Tag variant="solid" icon={<TagIcon />}>
          默认
        </Tag>
        <Tag color="success" variant="solid" icon={<Check />}>
          成功
        </Tag>
        <Tag color="info" variant="solid" icon={<Info />}>
          信息
        </Tag>
        <Tag color="warning" variant="solid" icon={<CircleAlert />}>
          警告
        </Tag>
        <Tag color="danger" variant="solid" icon={<CircleX />}>
          危险
        </Tag>
        <Tag color="#722ed1" variant="solid" icon={<Sparkles />}>
          自定义
        </Tag>
      </Flex>
    </Flex>
  );
}
```

展开代码

### 尺寸

通过 `size` 设置尺寸，默认为 `md`。


小

进行中

中

进行中

大

进行中

sizes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tag/sizes.tsx"
import { Flex, Grid, Tag, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const options = [
  { value: 'sm', label: '小' },
  { value: 'md', label: '中' },
  { value: 'lg', label: '大' },
] as const;

export function TagSizes() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <Tag size={value}>进行中</Tag>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}
```

展开代码

[](#)
### 可选标签

使用 `CheckableTag` 表示开关式选择，通过 `checked` 和 `onChange` 管理状态。


只看收藏

checkable.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tag/checkable.tsx"
import { CheckableTag } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function TagCheckable() {
  const [checked, setChecked] = useState(false);
  return (
    <CheckableTag checked={checked} onChange={setChecked}>
      只看收藏
    </CheckableTag>
  );
}
```

展开代码

### 标签组

使用 `TagGroup` 管理多个选项，`value` 和 `onChange` 使用字符串数组。


设计开发

已选：design

selection.tsx

复制代码

```tsx lineNumbers file="../../src/examples/tag/selection.tsx"
import { Space, TagGroup, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function TagSelection() {
  const [value, setValue] = useState<string[]>(['design']);
  return (
    <Space direction="vertical" align="stretch">
      <TagGroup
        options={[
          { value: 'design', label: '设计' },
          { value: 'dev', label: '开发' },
        ]}
        value={value}
        onChange={setValue}
      />
      <Text tone="muted" role="status">
        已选：{value.join(', ') || '无'}
      </Text>
    </Space>
  );
}
```

展开代码

设置 `name` 后，原生表单提交值为 JSON 数组字符串；未选择任何选项时为空字符串。受控标签组在表单重置时，需要同步重置应用状态。

### 关闭标签

设置 `closable` 后可关闭标签。通过 `onClose` 更新动态列表；调用 `event.preventDefault()` 可阻止默认移除。


LeafReact

closable.tsx

复制代码

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

export function TagClosable() {
  const [tags, setTags] = useState(['Leaf', 'React']);
  return (
    <Space wrap>
      {tags.map((tag) => (
        <Tag
          key={tag}
          closable
          onClose={() => setTags((items) => items.filter((item) => item !== tag))}
        >
          {tag}
        </Tag>
      ))}
      {tags.length === 0 && (
        <Text tone="muted" role="status">
          所有标签已关闭
        </Text>
      )}
    </Space>
  );
}
```

展开代码


## API

### Tag API

配置标签的内容、外观和关闭操作。

| 属性         | 类型                                                                           | 默认值         | 说明                                     |
| ---------- | ---------------------------------------------------------------------------- | ----------- | -------------------------------------- |
| `children` | `ReactNode`                                                                  | —           | 子内容。                                   |
| `color`    | `'default' \| 'success' \| 'warning' \| 'danger' \| 'info' \| (string & {})` | `'default'` | 默认灰色；也可使用四种语义预设或自定义颜色                  |
| `variant`  | `'soft' \| 'solid'`                                                          | `'soft'`    | `soft` 使用浅色背景和颜色文字，`solid` 使用颜色背景和白色文字 |
| `size`     | `'sm' \| 'md' \| 'lg'`                                                       | `'md'`      | 标签尺寸                                   |
| `icon`     | `ReactNode`                                                                  | —           | 显示自定义图标                                |
| `closable` | `boolean`                                                                    | `false`     | 展示关闭按钮                                 |
| `onClose`  | `(event: MouseEvent<HTMLButtonElement>) => void`                             | —           | 关闭时触发                                  |

### 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`   | —   | 禁用交互。 |
