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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/tag.md.

Tag 标签

标记内容的分类或状态。

基础用法

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

进行中
basic.tsx
import { Tag } from '@ifhover/leaf-ui';

export function TagBasic() {
  return <Tag>进行中</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
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
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
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
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
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
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

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

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

CheckableTagProps API

配置可选择标签的选中状态与变更事件。

属性类型默认值说明
checkedboolean—受控勾选状态
defaultCheckedbooleanfalse初始勾选状态
onChange(checked: boolean) => void—值变化回调
size'sm' | 'md' | 'lg''md'标签尺寸。

TagGroupProps API

管理标签选项组的选择值与显示方式。

属性类型默认值说明
optionsreadonly TagOption[]必填可用选项
valuereadonly string[]—受控值
defaultValuereadonly string[][]初始值;非受控表单 reset 时恢复
onChange(values: string[]) => void—值变化回调
disabledboolean—禁用交互。
size'sm' | 'md' | 'lg''md'标签尺寸。
namestring—表单字段名称
formstring—关联表单 ID
requiredboolean—要求整体值非空,复合控件只校验一次。

TagOption API

传入标签组的单个选项。

属性类型默认值说明
valuestring必填受控值
labelReactNode必填显示内容
disabledboolean—禁用交互。