Build faster with Premium Chakra UI Components 💎

Learn more
Skip to Content
DocsShowcaseBlogGuides
Sponsor

Checkbox Card

Used to select or deselect options displayed within cards.

SourceStorybookRecipeArk
AI TipWant to skip the docs? Use the MCP Server

Usage

import { CheckboxCard } from "@chakra-ui/react"
<CheckboxCard.Root>
  <CheckboxCard.HiddenInput />
  <CheckboxCard.Control>
    <CheckboxCard.Content>
      <CheckboxCard.Label />
      <CheckboxCard.Description />
    </CheckboxCard.Content>
    <CheckboxCard.Indicator />
  </CheckboxCard.Control>
</CheckboxCard.Root>
info
If you prefer a closed component composition, check out the snippet below.

Examples

Description

Use the CheckboxCard.Description component to add a description to the checkbox card.

Group

Use the CheckboxGroup component to group multiple checkbox cards.

Select framework(s)

Sizes

Pass the size prop to the CheckboxCard.Root component to change the size of the checkbox card.

Variants

Use the variant prop to Pass the variant prop to the CheckboxCard.Root component to change the variant of the checkbox card.

Disabled

Pass the disabled prop to the CheckboxCard.Root component to make the checkbox card disabled.

Addon

Render additional content within the CheckboxCard.Addon component to add some more context to the checkbox card.

No Indicator

Here's an example of how to use the checkbox card without an indicator.

Icon

Here's an example of how to render custom icons within the checkbox card.

Closed Component

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

import { CheckboxCard as ChakraCheckboxCard } from "@chakra-ui/react"
import * as React from "react"

export interface CheckboxCardProps extends ChakraCheckboxCard.RootProps {
  icon?: React.ReactElement
  label?: React.ReactNode
  description?: React.ReactNode
  addon?: React.ReactNode
  indicator?: React.ReactNode | null
  indicatorPlacement?: "start" | "end" | "inside"
  inputProps?: React.InputHTMLAttributes<HTMLInputElement>
}

export const CheckboxCard = React.forwardRef<
  HTMLInputElement,
  CheckboxCardProps
>(function CheckboxCard(props, ref) {
  const {
    inputProps,
    label,
    description,
    icon,
    addon,
    indicator = <ChakraCheckboxCard.Indicator />,
    indicatorPlacement = "end",
    ...rest
  } = props

  const hasContent = label || description || icon
  const ContentWrapper = indicator ? ChakraCheckboxCard.Content : React.Fragment

  return (
    <ChakraCheckboxCard.Root {...rest}>
      <ChakraCheckboxCard.HiddenInput ref={ref} {...inputProps} />
      <ChakraCheckboxCard.Control>
        {indicatorPlacement === "start" && indicator}
        {hasContent && (
          <ContentWrapper>
            {icon}
            {label && (
              <ChakraCheckboxCard.Label>{label}</ChakraCheckboxCard.Label>
            )}
            {description && (
              <ChakraCheckboxCard.Description>
                {description}
              </ChakraCheckboxCard.Description>
            )}
            {indicatorPlacement === "inside" && indicator}
          </ContentWrapper>
        )}
        {indicatorPlacement === "end" && indicator}
      </ChakraCheckboxCard.Control>
      {addon && <ChakraCheckboxCard.Addon>{addon}</ChakraCheckboxCard.Addon>}
    </ChakraCheckboxCard.Root>
  )
})

export const CheckboxCardIndicator = ChakraCheckboxCard.Indicator

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

npx @chakra-ui/cli snippet add checkbox-card

Here's how to use the it

<CheckboxCard label="Checkbox Card" />

Guides

CheckboxGroup + Field vs Fieldset

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

  • Single CheckboxCard: Can be wrapped with Field.Root for proper form field structure with labels and helper text
  • CheckboxGroup: Should be wrapped with Fieldset.Root, not Field.Root

A group of checkbox cards 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 card responds to clicks.

✅ Correct Usage:

<Fieldset.Root>
  <CheckboxGroup name="framework">
    <Fieldset.Legend>Select framework(s)</Fieldset.Legend>
    {/* ... checkbox cards ... */}
  </CheckboxGroup>
</Fieldset.Root>

❌ Incorrect Usage:

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

Props

Root

PropDefaultType
value on
string

The value of checkbox input. Useful for form submission.

colorPalette gray
'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'cyan' | 'purple' | 'pink'

The color palette of the component

size md
'sm' | 'md' | 'lg'

The size of the component

variant outline
'surface' | 'subtle' | 'outline' | 'solid'

The variant of the component

align start
'start' | 'end' | 'center'

The align of the component

orientation horizontal
'vertical' | 'horizontal'

The orientation of the component

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
unstyled
boolean

Whether to remove the component's style.

checked
CheckedState

The controlled checked state of the checkbox

defaultChecked
CheckedState

The initial checked state of the checkbox when rendered. Use when you don't need to control the checked state of the checkbox.

disabled
boolean

Whether the checkbox is disabled

form
string

The id of the form that the checkbox belongs to.

id
string

The unique identifier of the machine.

ids
Partial<{ root: string; hiddenInput: string; control: string; label: string }>

The ids of the elements in the checkbox. Useful for composition.

invalid
boolean

Whether the checkbox is invalid

name
string

The name of the input field in a checkbox. Useful for form submission.

onCheckedChange
(details: CheckedChangeDetails) => void

The callback invoked when the checked state changes.

readOnly
boolean

Whether the checkbox is read-only

required
boolean

Whether the checkbox is required

justify
'start' | 'end' | 'center'

The justify of the component

Explorer

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

Component Anatomy

Hover to highlight, click to select parts

root

control

label

description

addon

indicator

content

checkbox-card.recipe.ts

Previous

Checkbox

Next

Color Picker