Checkbox Card

Used to select or deselect options displayed within cards

Usage

import { CheckboxCard } from "chakra-ui-solid";

<CheckboxCard.Root>
  <CheckboxCard.HiddenInput />
  <CheckboxCard.Control>
    <CheckboxCard.Content>
      <CheckboxCard.Label />
      <CheckboxCard.Description />
    </CheckboxCard.Content>
    <CheckboxCard.Indicator />
  </CheckboxCard.Control>
</CheckboxCard.Root>

CheckboxCard.Root renders the <label> and CheckboxCard.HiddenInput renders the real <input type="checkbox"> inside it, so a click anywhere on the card toggles it. The input is not optional — without it there is nothing focusable, nothing to submit, and nothing for the label to point at.

It runs the same machine Checkbox does, so everything a checkbox composes with a checkbox card composes with too: CheckboxGroup, Field.Root and Fieldset.Root.

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

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.

Some supporting textNew

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.

No config

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>

Styling the box

The tick’s box — the border, the radius, the fill and its size — is on the indicator slot, which is the opposite of Checkbox, where the box lives on Checkbox.Control. Style CheckboxCard.Indicator to change how the tick looks and CheckboxCard.Control to change the card around it.

<CheckboxCard.Indicator borderRadius="full" />

Props

Root

CheckboxCardRootProps
Prop	Default	Type
`align`	`'start'`	`ConditionalValue<'start' \| 'end' \| 'center' \| PresetVariant<'checkboxCard', 'align'>>` Where they sit across it, and how the content's own text is aligned.
`checked`	—	`checkbox.CheckedState` The controlled checked state. Pass `undefined` for uncontrolled.
`defaultChecked`	—	`checkbox.CheckedState` The state a fresh, uncontrolled checkbox starts in.
`disabled`	—	`boolean` Whether the checkbox can be toggled or focused at all. Inherited from a surrounding Field.
`form`	—	`string` The id of a form elsewhere on the page that this checkbox submits with.
`id`	—	`string` Seeds every id the machine hands out — the root is `checkbox:{id}`, the hidden input `checkbox:{id}:input`. Defaults to a generated id, and does not become the root element's own `id`: pass `ids` to control the attributes themselves.
`ids`	—	`CheckboxElementIds` Override individual element ids, for pointing an ARIA relationship at a specific one.
`invalid`	—	`boolean` Whether the checkbox shows its error treatment. Inherited from a surrounding Field.
`justify`	—	`ConditionalValue<'start' \| 'end' \| 'center' \| PresetVariant<'checkboxCard', 'justify'>>` Where the control and the content sit along the main axis. Unset by default.
`name`	—	`string` The hidden input's `name`, for form submission.
`onCheckedChange`	—	`(details: CheckboxCheckedChangeDetails) => void` Called whenever the checked state changes, from either side.
`orientation`	`'horizontal'`	`ConditionalValue<'vertical' \| 'horizontal' \| PresetVariant<'checkboxCard', 'orientation'>>` Whether the control stacks its children in a row or a column.
`readOnly`	—	`boolean` Whether the checkbox refuses to change while staying focusable. Inherited from a Field.
`required`	—	`boolean` Whether the form requires this box to be ticked. Inherited from a surrounding Field.
`size`	`'md'`	`ConditionalValue<'sm' \| 'md' \| 'lg' \| PresetVariant<'checkboxCard', 'size'>>` The card's padding, its inner gap, the label's text style and the indicator's box.
`value`	`'on'`	`string` The hidden input's `value`, for form submission — and the key a `<CheckboxGroup>` tracks this box by.
`variant`	`'outline'`	`ConditionalValue<'surface' \| 'subtle' \| 'outline' \| 'solid' \| PresetVariant<'checkboxCard', 'variant'>>` How the card and its indicator are painted, at rest and once ticked.

Plus Omit<HTMLChakraProps<"label">, "id"> — the whole style-prop surface and the DOM attributes of the element it renders, several hundred names listed as their sources rather than expanded — and the three every component takes: as, render and unstyled.

RootProvider

CheckboxCardRootProviderProps
Prop	Default	Type
`align`	`'start'`	`ConditionalValue<'start' \| 'end' \| 'center' \| PresetVariant<'checkboxCard', 'align'>>` Where they sit across it, and how the content's own text is aligned.
`justify`	—	`ConditionalValue<'start' \| 'end' \| 'center' \| PresetVariant<'checkboxCard', 'justify'>>` Where the control and the content sit along the main axis. Unset by default.
`orientation`	`'horizontal'`	`ConditionalValue<'vertical' \| 'horizontal' \| PresetVariant<'checkboxCard', 'orientation'>>` Whether the control stacks its children in a row or a column.
`size`	`'md'`	`ConditionalValue<'sm' \| 'md' \| 'lg' \| PresetVariant<'checkboxCard', 'size'>>` The card's padding, its inner gap, the label's text style and the indicator's box.
`value`*	—	`CreateCheckboxCardReturn` A machine built by {@link createCheckboxCard}, so the consumer owns it rather than the Root.
`variant`	`'outline'`	`ConditionalValue<'surface' \| 'subtle' \| 'outline' \| 'solid' \| PresetVariant<'checkboxCard', 'variant'>>` How the card and its indicator are painted, at rest and once ticked.

Plus HTMLChakraProps<"label"> — the whole style-prop surface and the DOM attributes of the element it renders, several hundred names listed as their sources rather than expanded — and the three every component takes: as, render and unstyled.