# Checkbox **Category**: react **URL**: https://www.heroui.com/docs/react/components/checkbox **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/checkbox.mdx > Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected. *** ## Import ```tsx import { Checkbox, Label } from '@heroui/react'; ``` ### Usage ```tsx import {Checkbox, Label} from "@heroui/react"; export function Basic() { return ( ); } ``` ### Anatomy Import the Checkbox component and access all parts using dot notation. ```tsx import { Checkbox, Label, Description } from '@heroui/react'; export default () => ( ); ``` ### Disabled ```tsx import {Checkbox, Description, Label} from "@heroui/react"; export function Disabled() { return ( This feature is coming soon ); } ``` ### Default Selected ```tsx import {Checkbox, Label} from "@heroui/react"; export function DefaultSelected() { return ( ); } ``` ### Controlled ```tsx "use client"; import {Checkbox, Label} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [isSelected, setIsSelected] = useState(true); return (

Status: {isSelected ? "Enabled" : "Disabled"}

); } ``` ### Indeterminate ```tsx "use client"; import {Checkbox, Description, Label} from "@heroui/react"; import {useState} from "react"; export function Indeterminate() { const [isIndeterminate, setIsIndeterminate] = useState(true); const [isSelected, setIsSelected] = useState(false); return ( { setIsSelected(selected); setIsIndeterminate(false); }} > Shows indeterminate state (dash icon) ); } ``` ### With Label ```tsx import {Checkbox, Label} from "@heroui/react"; export function WithLabel() { return ( ); } ``` ### With Description ```tsx import {Checkbox, Description, Label} from "@heroui/react"; export function WithDescription() { return ( Get notified when someone mentions you in a comment ); } ``` ### Render Props ```tsx "use client"; import {Checkbox, Description, Label} from "@heroui/react"; export function RenderProps() { return ( {({isSelected}) => ( <> {isSelected ? "Thank you for accepting" : "Please read and accept the terms"} )} ); } ``` ### Form Integration ```tsx "use client"; import {Button, Checkbox, Label} from "@heroui/react"; import React from "react"; export function Form() { const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); const formData = new FormData(e.target as HTMLFormElement); alert( `Form submitted with:\n${Array.from(formData.entries()) .map(([key, value]) => `${key}: ${value}`) .join("\n")}`, ); }; return (
); } ``` ### Invalid ```tsx import {Checkbox, Description, Label} from "@heroui/react"; export function Invalid() { return ( You must accept the terms to continue ); } ``` ### Custom Indicator ```tsx "use client"; import {Checkbox, Label} from "@heroui/react"; export function CustomIndicator() { return (
{({isSelected}) => isSelected ? ( ) : null } {({isSelected}) => isSelected ? ( ) : null } {({isIndeterminate}) => isIndeterminate ? ( ) : null }
); } ``` ### Full Rounded ```tsx import {Checkbox, Label} from "@heroui/react"; export function FullRounded() { return (
); } ``` ### Variants The Checkbox component supports two visual variants: - **`primary`** (default) - Standard styling with default background, suitable for most use cases - **`secondary`** - Lower emphasis variant, suitable for use in Surface components ```tsx import {Checkbox, Description, Label} from "@heroui/react"; export function Variants() { return (

Primary variant

Standard styling with default background

Secondary variant

Lower emphasis variant for use in surfaces
); } ``` ### Custom Render Function ```tsx "use client"; import {Checkbox, Label} from "@heroui/react"; export function CustomRenderFunction() { return (
); } ``` ## Related Components - **Label**: Accessible label for form controls - **CheckboxGroup**: Group of checkboxes with shared state - **Description**: Helper text for form fields ## Styling ### Passing Tailwind CSS classes You can customize individual Checkbox components: ```tsx import { Checkbox, Label } from '@heroui/react'; function CustomCheckbox() { return ( ); } ``` ### Customizing the component classes To customize the Checkbox component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .checkbox { @apply inline-flex gap-3 items-center; } .checkbox__control { @apply size-5 border-2 border-gray-400 rounded data-[selected=true]:bg-blue-500 data-[selected=true]:border-blue-500; /* Animated background indicator */ &::before { @apply bg-accent pointer-events-none absolute inset-0 z-0 origin-center scale-50 rounded-md opacity-0 content-['']; transition: scale 200ms linear, opacity 200ms linear, background-color 200ms ease-out; } /* Show indicator when selected */ &[data-selected="true"]::before { @apply scale-100 opacity-100; } } .checkbox__indicator { @apply text-white; } .checkbox__content { @apply flex flex-col gap-1; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Checkbox component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox.css)): - `.checkbox` - Base checkbox container - `.checkbox__control` - Checkbox control box - `.checkbox__indicator` - Checkbox checkmark indicator - `.checkbox__content` - Optional content container ### Interactive States The checkbox supports both CSS pseudo-classes and data attributes for flexibility: - **Selected**: `[data-selected="true"]` or `[aria-checked="true"]` (shows checkmark and background color change) - **Indeterminate**: `[data-indeterminate="true"]` (shows indeterminate state with dash) - **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` (shows error state with danger colors) - **Hover**: `:hover` or `[data-hovered="true"]` - **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring) - **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events) - **Pressed**: `:active` or `[data-pressed="true"]` ## API Reference ### Checkbox Props Inherits from [React Aria Checkbox](https://react-spectrum.adobe.com/react-aria/Checkbox.html). | Prop | Type | Default | Description | |------|------|---------|-------------| | `isSelected` | `boolean` | `false` | Whether the checkbox is checked | | `defaultSelected` | `boolean` | `false` | Whether the checkbox is checked by default (uncontrolled) | | `isIndeterminate` | `boolean` | `false` | Whether the checkbox is in an indeterminate state | | `isDisabled` | `boolean` | `false` | Whether the checkbox is disabled | | `isInvalid` | `boolean` | `false` | Whether the checkbox is invalid | | `isReadOnly` | `boolean` | `false` | Whether the checkbox is read only | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | | `name` | `string` | - | The name of the input element, used when submitting an HTML form | | `value` | `string` | - | The value of the input element, used when submitting an HTML form | | `onChange` | `(isSelected: boolean) => void` | - | Handler called when the checkbox value changes | | `children` | `React.ReactNode \| (values: CheckboxRenderProps) => React.ReactNode` | - | Checkbox content or render prop | | `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function.| ### CheckboxRenderProps When using the render prop pattern, these values are provided: | Prop | Type | Description | |------|------|-------------| | `isSelected` | `boolean` | Whether the checkbox is currently checked | | `isIndeterminate` | `boolean` | Whether the checkbox is in an indeterminate state | | `isHovered` | `boolean` | Whether the checkbox is hovered | | `isPressed` | `boolean` | Whether the checkbox is currently pressed | | `isFocused` | `boolean` | Whether the checkbox is focused | | `isFocusVisible` | `boolean` | Whether the checkbox is keyboard focused | | `isDisabled` | `boolean` | Whether the checkbox is disabled | | `isReadOnly` | `boolean` | Whether the checkbox is read only |