# Chip · HeroUI

> Migration guide for Chip from HeroUI v2 to v3

- Page: https://jiguang132.com/systems/heroui/docs/migration/chip
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

> 
  Refer to the [v3 Chip documentation](/systems/heroui/docs/components/chip) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.


## 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 ``, so explicit usage is optional but available for custom styling.

```tsx
{/* 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`.

```tsx
<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

| v2 Prop | v3 Location | Notes |
|---------|-------------|-------|
| `radius` | - | Removed (use Tailwind e.g. `rounded-full`) |
| `avatar` | - | Use children (e.g. `` as first child) |
| `startContent`, `endContent` | - | Use children directly |
| `onClose` | - | Implement close manually (e.g. `CloseButton`) |
| `classNames` | - | Use `className` |
| `isDisabled` | - | Use conditional rendering or Tailwind (e.g. `opacity-50`) |

### 7. 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 |

### 8. 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 |

## Structure Changes

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

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

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

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

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

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

## Migration Examples

### Variants and Colors


  

#### v2


    ```tsx
    {/* 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>
    ```
  
  

#### v3


    ```tsx
    {/* 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


  

#### v2


    ```tsx
    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>
    ```
  
  

#### v3


    ```tsx
    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


  

#### v2


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

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

#### 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>
    ```
  


### With Close Button


  

#### v2


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

#### v3


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

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


### Removed Variants


  

#### v2


    ```tsx
    {/* Dot variant */}
    <Chip variant="dot">Dot</Chip>
    
    {/* Shadow variant */}
    <Chip variant="shadow">Shadow</Chip>
    ```
  
  

#### v3


    ```tsx
    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

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

### v3: Direct `className` Prop

```tsx
<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

---

Index of all JGuang resources: https://jiguang132.com/llms.txt