Chip

Key Changes

1. Variants

v2: solid, bordered, light, flat, faded, shadow, dot
v3: primary, secondary, tertiary, soft

2. Colors

v2: default, primary, secondary, success, warning, danger
v3: default, accent, success, warning, danger

3. Compound Component Pattern

v3 introduces a compound component pattern with the Chip.Label subcomponent:

• Chip.Label -- Renders the label text inside the chip. Plain-text children are automatically wrapped in <Chip.Label>, so explicit usage is optional but available for custom styling.

{/* Implicit label -- plain text is auto-wrapped in Chip.Label */}
<Chip>Badge</Chip>

{/* Explicit label -- useful when you need a custom className */}
<Chip>
  <Chip.Label className="uppercase tracking-wide">Badge</Chip.Label>
</Chip>

4. Size Variants

v2: sm, md, lg (via the size prop) v3: sm, md, lg (via the size prop -- same API)

The available sizes remain the same, but v3 applies them through BEM-style CSS classes (chip--sm, chip--md, chip--lg). The default size is md.

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

5. Compound Variant Classes

v3 supports combining variant and color classes for precise styling. These compound classes have default styles defined in the CSS:

Primary variant combinations: .chip--primary.chip--accent, .chip--primary.chip--success, .chip--primary.chip--warning, .chip--primary.chip--danger

Soft variant combinations: .chip--accent.chip--soft, .chip--success.chip--soft, .chip--warning.chip--soft, .chip--danger.chip--soft

You can also target any other combination (e.g., .chip--secondary.chip--accent) via the @layer components directive in your CSS.

6. Prop Changes

7. Variant Mapping

8. Color Mapping

Structure Changes

In v2, Chip was a component that accepted various props for styling:

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

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

In v3, Chip has a simplified API with fewer variants:

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

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

Migration Examples

Variants and Colors

{/* Variants */}
<Chip variant="solid">Solid</Chip>
<Chip variant="bordered">Bordered</Chip>
<Chip variant="light">Light</Chip>

{/* Colors */}
<Chip color="primary">Primary</Chip>
<Chip color="success">Success</Chip>

{/* Variants */}
<Chip variant="primary">Primary</Chip>
<Chip variant="secondary">Secondary</Chip>
<Chip variant="soft">Soft</Chip>

{/* Colors */}
<Chip color="accent">Accent</Chip>
<Chip color="success">Success</Chip>

With Icons

import { Icon } from "@iconify/react";

{/* Start content */}
<Chip startContent={<Icon icon="gravity-ui:check" />}>
  Chip
</Chip>

{/* End content */}
<Chip endContent={<Icon icon="gravity-ui:chevron-down" />}>
  Chip
</Chip>

import { Icon } from "@iconify/react";

{/* Start content */}
<Chip>
  <Icon icon="gravity-ui:check" />
  Chip
</Chip>

{/* End content */}
<Chip>
  Chip
  <Icon icon="gravity-ui:chevron-down" />
</Chip>

With Avatar

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

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

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>

With Close Button

<Chip onClose={() => console.log("close")}>
  Chip
</Chip>

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

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

Removed Variants

{/* Dot variant */}
<Chip variant="dot">Dot</Chip>

{/* Shadow variant */}
<Chip variant="shadow">Shadow</Chip>

import { Icon } from "@iconify/react";

{/* Dot variant - implement manually */}
<Chip>
  <Icon icon="gravity-ui:circle-fill" width={6} />
  Dot
</Chip>

{/* Shadow variant - use Tailwind classes */}
<Chip variant="primary" className="shadow-md">
  Shadow
</Chip>

Styling Changes

v2: classNames Prop

<Chip 
  classNames={{
    base: "custom-base",
    content: "custom-content",
    dot: "custom-dot",
    avatar: "custom-avatar",
    closeButton: "custom-close-button"
  }}
/>

v3: Direct className Prop

<Chip className="custom-base">
  {/* Content with custom classes */}
  <span className="custom-content">Chip</span>
</Chip>

Summary

1. Variants Reduced: From 7 variants to 4 variants
2. Color Changes: primary → accent, secondary removed
3. Compound Component: Chip.Label subcomponent added; plain-text children are auto-wrapped
4. Size Variants: sm, md, lg remain available via the size prop, now applied as BEM classes (chip--sm, chip--md, chip--lg)
5. Compound Variant Classes: Variant + color combinations (e.g., .chip--primary.chip--accent, .chip--soft.chip--success) have built-in styles and are customizable via @layer components
6. Radius Removed: Use Tailwind CSS classes instead
7. Avatar Prop Removed: Use children directly
8. Start/End Content Removed: Use children directly
9. Close Button Removed: Implement manually with CloseButton component
10. Dot Variant Removed: Implement manually with icon
11. Shadow Variant Removed: Use Tailwind shadow-* classes
12. Disabled Prop Removed: Use conditional rendering or CSS classes
13. ClassNames Removed: Use className prop directly