Chip

Refer to the v3 Chip documentation for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.

Overview

The Chip component in HeroUI v3 has been simplified with a streamlined API, fewer variants, and removal of styling props in favor of Tailwind CSS customization.

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. Removed Props

The following props are no longer available in v3:

radius - Use Tailwind CSS classes like rounded-full, rounded-lg, rounded-md
avatar - Use children directly (e.g., <Avatar /> as first child)
startContent - Use children directly (e.g., icon as first child)
endContent - Use children directly (e.g., icon as last child)
onClose - Implement close functionality manually with a button
classNames - Use className prop directly
isDisabled - Use disabled attribute or conditional rendering

4. Variant Mapping

v2 Variant	v3 Equivalent	Notes
`solid`	`primary`	Filled background
`bordered`	`secondary`	Border with transparent background
`light`	`soft`	Light background
`flat`	`tertiary`	Transparent background
`faded`	`secondary`	Similar appearance
`shadow`	`primary`	Use Tailwind `shadow-*` classes
`dot`	-	Not available, implement manually

5. Color Mapping

v2 Color	v3 Equivalent	Notes
`default`	`default`	Same
`primary`	`accent`	Renamed
`secondary`	`default` or `accent`	Depends on context
`success`	`success`	Same
`warning`	`warning`	Same
`danger`	`danger`	Same

Migration Examples

Basic Usage

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

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

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

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

Variants

<Chip variant="solid">Solid</Chip>
<Chip variant="bordered">Bordered</Chip>
<Chip variant="light">Light</Chip>
<Chip variant="flat">Flat</Chip>
<Chip variant="faded">Faded</Chip>
<Chip variant="shadow">Shadow</Chip>

<Chip variant="primary">Primary</Chip>
<Chip variant="secondary">Secondary</Chip>
<Chip variant="soft">Soft</Chip>
<Chip variant="tertiary">Tertiary</Chip>

Colors

<Chip color="default">Default</Chip>
<Chip color="primary">Primary</Chip>
<Chip color="secondary">Secondary</Chip>
<Chip color="success">Success</Chip>
<Chip color="warning">Warning</Chip>
<Chip color="danger">Danger</Chip>

<Chip color="default">Default</Chip>
<Chip color="accent">Accent</Chip>
<Chip color="success">Success</Chip>
<Chip color="warning">Warning</Chip>
<Chip color="danger">Danger</Chip>

Radius

<Chip radius="full">Full</Chip>
<Chip radius="lg">Large</Chip>
<Chip radius="md">Medium</Chip>
<Chip radius="sm">Small</Chip>

<Chip className="rounded-full">Full</Chip>
<Chip className="rounded-lg">Large</Chip>
<Chip className="rounded-md">Medium</Chip>
<Chip className="rounded-sm">Small</Chip>

With Icons (Start Content)

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

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

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

<Chip>
  <Icon icon="gravity-ui:check" />
  Chip
</Chip>

With Icons (End Content)

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

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

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

<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 } from "@heroui/react";

<Chip variant="tertiary">
  <Avatar name="JW" src="https://example.com/avatar.jpg" />
  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>

Dot Variant

<Chip variant="dot">Dot</Chip>

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

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

Shadow Variant

<Chip variant="shadow">Shadow</Chip>

<Chip variant="primary" className="shadow-md">
  Shadow
</Chip>

Disabled State

<Chip isDisabled>Disabled</Chip>

{/* Use conditional rendering or disabled attribute */}
<Chip className="opacity-50 cursor-not-allowed">
  Disabled
</Chip>

Custom Styles

<Chip 
  classNames={{
    base: "custom-base",
    content: "custom-content"
  }}
>
  Custom
</Chip>

<Chip className="custom-base">
  <span className="custom-content">Custom</span>
</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>

Breaking Changes Summary

Variants Reduced: From 7 variants to 4 variants
Color Changes: primary → accent, secondary removed
Radius Removed: Use Tailwind CSS classes instead
Avatar Prop Removed: Use children directly
Start/End Content Removed: Use children directly
Close Button Removed: Implement manually with CloseButton component
Dot Variant Removed: Implement manually with icon
Shadow Variant Removed: Use Tailwind shadow-* classes
Disabled Prop Removed: Use conditional rendering or CSS classes
ClassNames Removed: Use className prop directly

Tips for Migration

Map variants: Use the variant mapping table to find equivalent v3 variants
Update colors: Change primary to accent, remove secondary usage
Move content: Place icons, avatars, and other content as children instead of props
Implement close: Use CloseButton component for close functionality
Use Tailwind: Apply radius, shadows, and other styling with Tailwind classes
Dot variant: Use an icon component as the first child to replicate dot variant

Need Help?

For v3 Chip features and API:

See the API Reference
Check interactive examples

For community support:

On this page