Chip

<Callout type="info"> 完整的 API 参考、样式指南与高级示例请参阅 [v3 Chip 文档](/docs/react/components/chip)。本指南只关注从 HeroUI v2 的迁移。 </Callout>

关键变化

1. 变体

v2： solid、bordered、light、flat、faded、shadow、dot
v3： primary、secondary、tertiary、soft

2. 颜色

v2： default、primary、secondary、success、warning、danger
v3： default、accent、success、warning、danger

3. 复合组件模式

v3 引入复合组件模式，并提供 Chip.Label 子组件：

Chip.Label：渲染 Chip 内的标签文本。纯文本 children 会自动包在 <Chip.Label> 中，因此多数场景不必手写；需要自定义 className 时可显式使用。

tsx

<Chip>Badge</Chip>
<Chip>
  <Chip.Label className="uppercase tracking-wide">Badge</Chip.Label>
</Chip>

4. 尺寸变体

v2： sm、md、lg（通过 size prop）
v3： sm、md、lg（通过 size prop，API 相同）

可用尺寸与 v2 一致，但 v3 通过 BEM 风格的 CSS class（chip--sm、chip--md、chip--lg）应用。默认尺寸为 md。

tsx

<Chip size="sm">Small</Chip>
<Chip size="md">Medium (default)</Chip>
<Chip size="lg">Large</Chip>

5. 复合变体 class

v3 支持组合变体与颜色 class，以实现更精细的样式。下列复合 class 在 CSS 中带有默认样式：

primary 变体组合： .chip--primary.chip--accent、.chip--primary.chip--success、.chip--primary.chip--warning、.chip--primary.chip--danger

soft 变体组合： .chip--accent.chip--soft、.chip--success.chip--soft、.chip--warning.chip--soft、.chip--danger.chip--soft

你也可以在 CSS 中通过 @layer components 为其他任意组合（例如 .chip--secondary.chip--accent）补充样式。

6. Prop 变更

v2 prop	v3 位置	说明
`radius`	—	已移除（例如使用 Tailwind `rounded-full`）
`avatar`	—	使用 `children`（例如将 `<Avatar />` 作为第一个子节点）
`startContent`、`endContent`	—	直接使用 `children`
`onClose`	—	手动实现关闭（例如使用 `CloseButton`）
`classNames`	—	使用 `className`
`isDisabled`	—	使用条件渲染或 Tailwind（例如 `opacity-50`）

7. 变体映射

v2 变体	v3 对应	说明
`solid`	`primary`	实心背景
`bordered`	`secondary`	边框 + 透明背景
`light`	`soft`	浅色背景
`flat`	`tertiary`	透明背景
`faded`	`secondary`	观感相近
`shadow`	`primary`	配合 Tailwind `shadow-*` class
`dot`	—	不再内置，请自行实现

8. 颜色映射

v2 颜色	v3 对应	说明
`default`	`default`	相同
`primary`	`accent`	已重命名
`secondary`	`default` 或 `accent`	视场景选择
`success`	`success`	相同
`warning`	`warning`	相同
`danger`	`danger`	相同

结构变化

在 v2 中，Chip 是一个通过大量 prop 控制样式的组件：

tsx

import { Chip } from "@heroui/react";

export default function App() {
  return <Chip>Chip</Chip>;
}

在 v3 中，Chip 的 API 更精简，变体更少：

tsx

import { Chip } from "@heroui/react";

export default function App() {
  return <Chip>Chip</Chip>;
}

迁移示例

变体与颜色

<Tabs items={["v2", "v3"]}> <Tab value="v2"> tsx <Chip variant="solid">Solid</Chip> <Chip variant="bordered">Bordered</Chip> <Chip variant="light">Light</Chip> <Chip color="primary">Primary</Chip> <Chip color="success">Success</Chip> </Tab> <Tab value="v3"> tsx <Chip variant="primary">Primary</Chip> <Chip variant="secondary">Secondary</Chip> <Chip variant="soft">Soft</Chip> <Chip color="accent">Accent</Chip> <Chip color="success">Success</Chip> </Tab> </Tabs>

带图标

<Tabs items={["v2", "v3"]}> <Tab value="v2"> tsx import { Icon } from "@iconify/react"; <Chip startContent={<Icon icon="gravity-ui:check" />}> Chip </Chip> <Chip endContent={<Icon icon="gravity-ui:chevron-down" />}> Chip </Chip> </Tab> <Tab value="v3"> tsx import { Icon } from "@iconify/react"; <Chip> <Icon icon="gravity-ui:check" /> Chip </Chip> <Chip> Chip <Icon icon="gravity-ui:chevron-down" /> </Chip> </Tab> </Tabs>

带 Avatar

<Tabs items={["v2", "v3"]}> <Tab value="v2"> ```tsx import { Avatar } from "@heroui/react";

<Chip
  avatar={<Avatar name="JW" src="https://example.com/avatar.jpg" />}
  variant="flat"
>
  Avatar
</Chip>
```

</Tab> <Tab value="v3"> ```tsx import { Avatar, Chip } from "@heroui/react";

<Chip variant="tertiary">
  <Avatar size="sm">
    <Avatar.Image src="https://example.com/avatar.jpg" alt="JW" />
    <Avatar.Fallback>JW</Avatar.Fallback>
  </Avatar>
  Avatar
</Chip>
```

</Tab> </Tabs>

带关闭按钮

<Tabs items={["v2", "v3"]}> <Tab value="v2"> tsx <Chip onClose={() => console.log("close")}> Chip </Chip> </Tab> <Tab value="v3"> ```tsx import { CloseButton } from "@heroui/react";

<Chip>
  Chip
  <CloseButton 
    aria-label="Close chip"
    onPress={() => console.log("close")}
  />
</Chip>
```