# Checkbox
**Category**: react
**URL**: https://heroui.com/en/docs/react/migration/checkbox
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/migration/(components)/checkbox.mdx
> Migration guide for Checkbox from HeroUI v2 to v3
***
Refer to the [v3 Checkbox documentation](/docs/react/components/checkbox) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
## Structure Changes
In v2, `Checkbox` accepted children as the label:
```tsx
import { Checkbox } from "@heroui/react";
export default function App() {
return Option;
}
```
In v3, Checkbox uses a compound component pattern with explicit subcomponents:
```tsx
import { Checkbox, Label } from "@heroui/react";
export default function App() {
return (
Option
);
}
```
## Key Changes
### 1. Component Structure
**v2:** Simple component with children as label
**v3:** Compound components: `Checkbox.Content`, `Checkbox.Control`, `Checkbox.Indicator`
### 2. Label Handling
**v2:** Label passed as children directly to `Checkbox`
**v3:** Label goes inside `Checkbox.Content` (the clickable label); `Description`/`FieldError` are siblings of `Checkbox.Content`
### 3. Prop Changes
| v2 Prop | v3 Location | Notes |
|---------|-------------|-------|
| `onValueChange` | `Checkbox` | Use `onChange` |
| `color` | - | Removed (use Tailwind on Checkbox.Control) |
| `size` | - | Removed (use Tailwind e.g. `size-4`, `size-5`) |
| `radius` | - | Removed (use Tailwind e.g. `rounded-sm`) |
| `lineThrough` | - | Removed (use Tailwind `line-through` on label) |
| `icon` | - | Use custom content in `Checkbox.Indicator` |
| `classNames` | - | Use `className` on parts |
| `disableAnimation` | - | Removed |
| — | `variant` | New prop: `"primary"` (default) or `"secondary"` for lower emphasis styling |
### 4. CheckboxGroup Changes
**v2:** `CheckboxGroup` (separate component) with `label` prop and simple `Checkbox` children
**v3:** `CheckboxGroup` (separate component) with `Label`/`Description` as children and compound `Checkbox` structure
For migrating checkbox groups, see the [CheckboxGroup migration guide](/docs/react/migration/checkbox-group).
## Migration Examples
### Controlled Checkbox
```tsx
import { useState } from "react";
const [isSelected, setIsSelected] = useState(false);
Subscribe
```
```tsx
import { useState } from "react";
import { Label } from "@heroui/react";
const [isSelected, setIsSelected] = useState(false);
Subscribe
```
### Checkbox with Description
```tsx
{/* v2 doesn't have built-in description support */}
Option
Description text
```
```tsx
import { Checkbox, Label, Description } from "@heroui/react";
Option
Description text
```
### CheckboxGroup
```tsx
import { Checkbox, CheckboxGroup } from "@heroui/react";
Buenos Aires
Sydney
San Francisco
```
```tsx
import { CheckboxGroup, Checkbox, Label, Description } from "@heroui/react";
Choose all that apply
Buenos Aires
Sydney
San Francisco
```
### Colors and Sizes
```tsx
{/* Colors */}
Primary
{/* Sizes */}
Medium
```
```tsx
{/* Colors - use Tailwind classes */}
Primary
{/* Sizes - use Tailwind classes */}
Medium
```
### Custom Icon/Indicator
```tsx
}>
Option
```
```tsx
{({isSelected}) => isSelected ? : null}
Option
```
### Variants
v3 introduces a `variant` prop with `"primary"` (default) and `"secondary"` options:
```tsx
{/* Primary variant (default) */}
Primary
{/* Secondary variant - lower emphasis, suitable for Surface components */}
Secondary
```
### Indeterminate State
```tsx
Option
```
```tsx
Option
```
## Render Props Pattern
v3 Checkbox supports a render prop pattern that provides state information:
```tsx
{({isSelected, isIndeterminate, isHovered, isPressed, isFocused, isDisabled}) => (
<>
{isSelected ? "Terms accepted" : "Accept terms"}
)}
```
`Checkbox.Indicator` also supports a render prop pattern, providing the same state values. This is useful for rendering custom indicator content based on the checkbox state:
```tsx
{({isSelected, isIndeterminate}) =>
isIndeterminate ? : isSelected ? : null
}
Custom indicator
```
Available render props:
- `isSelected` - Whether checkbox is checked
- `isIndeterminate` - Whether checkbox is in indeterminate state
- `isHovered` - Whether checkbox is hovered
- `isPressed` - Whether checkbox is currently pressed
- `isFocused` - Whether checkbox is focused
- `isFocusVisible` - Whether checkbox should show focus indicator
- `isDisabled` - Whether checkbox is disabled
- `isReadOnly` - Whether checkbox is read only
## Styling Changes
### v2: `classNames` Prop
```tsx
```
### v3: Direct `className` Props
```tsx
Option
```
## Component Anatomy
The v3 Checkbox follows this structure:
```
Checkbox (Root)
├── Checkbox.Content (the clickable label)
│ ├── Checkbox.Control
│ │ └── Checkbox.Indicator
│ └── Label
├── Description (optional, sibling)
└── FieldError (optional, sibling)
```
## Summary
1. **Component Structure**: Must use compound components (`Button`, `Control`, `Indicator`)
2. **Label Handling**: Labels go inside `Checkbox.Content`
3. **onValueChange → onChange**: Event handler prop renamed
4. **Color Removed**: Use Tailwind CSS classes on `Checkbox.Control`
5. **Size Removed**: Use Tailwind CSS classes on `Checkbox.Control`
6. **Radius Removed**: Use Tailwind CSS classes on `Checkbox.Control`
7. **LineThrough Removed**: Use Tailwind `line-through` class on label
8. **Icon Prop Removed**: Use custom content in `Checkbox.Indicator`
9. **CheckboxGroup**: Same component name; use `Label`/`Description` as children and compound `Checkbox` structure
10. **ClassNames Removed**: Use `className` props on individual components
11. **New `variant` Prop**: Supports `"primary"` (default) and `"secondary"` for lower emphasis styling
12. **Indicator Render Props**: `Checkbox.Indicator` accepts a render function with state values (`isSelected`, `isIndeterminate`, etc.)