Checkbox

Usage

import { Checkbox } from "@chakra-ui/react"

<Checkbox.Root>
  <Checkbox.HiddenInput />
  <Checkbox.Control>
    <Checkbox.Indicator />
  </Checkbox.Control>
  <Checkbox.Label />
</Checkbox.Root>

Shortcuts

The Checkbox component also provides a set of shortcuts for common use cases.

CheckboxControl

This component renders the Checkbox.Indicator within it by default.

This works:

<Checkbox.Control>
  <Checkbox.Indicator />
</Checkbox.Control>

This might be more concise, if you don't need to customize the indicator:

<Checkbox.Control />

Examples

Variants

Pass the variant prop to the Checkbox.Root component to change the visual style of the checkbox.

Colors

Pass the colorPalette prop to the Checkbox.Root component to change the color of the checkbox.

Sizes

Pass the size prop to the Checkbox.Root component to change the size of the checkbox.

States

Pass the disabled or invalid prop to the Checkbox.Root component to change the visual state of the checkbox.

Controlled

Use the checked and onCheckedChange props to control the state of the checkbox.

Label Position

Here's an example of how to change the label position to the right.

Store

An alternative way to control the checkbox is to use the RootProvider component and the useCheckbox store hook.

This way you can access the checkbox state and methods from outside the checkbox.

Composition

Here's an example of how to compose a checkbox with a field component.

Hook Form

Here's an example of how to use the Checkbox component with the react-hook-form library.

Group

Use the CheckboxGroup component to group multiple checkboxes together.

Group Hook Form

Here's an example of how to use the CheckboxGroup component with the react-hook-form library.

Custom Icon

Render a custom icon within Checkbox.Control to change the icon of the checkbox.

Indeterminate

Set the checked prop to indeterminate to show the checkbox in an indeterminate state.

Description

Here's an example of how to add some further description to the checkbox.

Link

Render an anchor tag within the Checkbox.Label to add a link to the label.

Closed Component

Here's how to setup the Checkbox for a closed component composition.

import { Checkbox as ChakraCheckbox } from "@chakra-ui/react"
import * as React from "react"

export interface CheckboxProps extends ChakraCheckbox.RootProps {
  icon?: React.ReactNode
  inputProps?: React.InputHTMLAttributes<HTMLInputElement>
  rootRef?: React.RefObject<HTMLLabelElement | null>
}

export const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
  function Checkbox(props, ref) {
    const { icon, children, inputProps, rootRef, ...rest } = props
    return (
      <ChakraCheckbox.Root ref={rootRef} {...rest}>
        <ChakraCheckbox.HiddenInput ref={ref} {...inputProps} />
        <ChakraCheckbox.Control>
          {icon || <ChakraCheckbox.Indicator />}
        </ChakraCheckbox.Control>
        {children != null && (
          <ChakraCheckbox.Label>{children}</ChakraCheckbox.Label>
        )}
      </ChakraCheckbox.Root>
    )
  },
)

If you want to automatically add the closed component to your project, run the command:

npx @chakra-ui/cli snippet add checkbox

Here's how to use the it

<Checkbox>Accept terms and conditions</Checkbox>

Guides

CheckboxGroup + Field vs Fieldset

When working with multiple checkboxes, it's important to understand the semantic difference between Field and Fieldset:

• Single Checkbox: Wrap with Field.Root for proper form field structure with labels and helper text
• CheckboxGroup: Wrap with Fieldset.Root, not Field.Root

A checkbox group represents a collection of related options and should be marked up as a fieldset with a legend, not as a single field. Wrapping CheckboxGroup in Field.Root can cause interaction issues where only the first checkbox responds to clicks.

✅ Correct Usage:

<Fieldset.Root>
  <CheckboxGroup name="framework">
    <Fieldset.Legend>Select framework</Fieldset.Legend>
    {/* ... checkboxes ... */}
  </CheckboxGroup>
</Fieldset.Root>

❌ Incorrect Usage:

// Don't wrap CheckboxGroup with Field.Root
<Field.Root>
  <CheckboxGroup>{/* ... checkboxes ... */}</CheckboxGroup>
</Field.Root>

Props

Root

Explorer

Explore the Checkbox component parts interactively. Click on parts in the sidebar to highlight them in the preview.