> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Checkbox

> Checkboxes allow users to select one or multiple options from a list.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-checkbox--docs)

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-checkbox--default" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-checkbox--default&viewMode=story&globals=theme:light" title="Checkbox default story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## When to use

Checkboxes can be used as stand-alone elements or embedded in other components such as Menus, Tree views, Data tables, or Cards, where a user can select one or more options.

* Users need to select multiple options independently (e.g., hiding or showing columns in a Data Table display).
* Users need to enable/disable a setting.
* A selection doesn't require immediate action (e.g., form submission required to apply changes).
* User needs to confirm or agree to something (e.g., a delete confirmation)

## When to use something else

* The user should only select one option. Use [Radio](/cdf/aura/primitives/radio) buttons instead.
* The options are part of a form and don't need to be presented all at once—consider [Select](/cdf/aura/primitives/select).
* The action is immediate and toggles a setting on/off. Use [Switch](/cdf/aura/primitives/switch) instead. Checkboxes indicate selection rather than an instant toggle, so they can feel ambiguous for immediate on/off settings.

## Dos and don'ts

* **Do** provide a label to help the user understand what they are selecting.
* **Do** use an indeterminate state when some of the children items are selected.
* **Do** automatically select children when a parent item is selected.
* **Do** always indent children items to show the parent-child relationship.
* **Don't** preselect Checkboxes for the user as this can be overlooked.
* **Don't** use only one checkbox unless it's being used to verify or agree to something.

## Behavior

### Parent and child checkbox

Checkboxes should work independently from each other: selecting one Checkbox shouldn't change the selection status of another Checkbox in the list of the same hierarchy. The exception is when a parent Checkbox is used to select the children items:

* When a child is unselected while other children are selected, the parent Checkbox becomes indeterminate.
* When a parent Checkbox is selected, all children are selected
* When a parent Checkbox is unselected, all children are unselected.

### Triggering changes

A Checkbox does not immediately trigger a change. Checkboxes should always be accompanied with a "Submit", "Save" or alternative action button to trigger the change. If immediate change is expected, use a [Switch](/cdf/aura/primitives/switch) instead.

## Checkbox vs Checkbox + card

* Use a plain checkbox when the options are straightforward and self-explanatory — enabling a feature, agreeing to terms, selecting items from a list.
* Use the card container when:
  * Each option benefits from a description to make the choice clear.
  * The options represent distinct configurations or feature sets the user needs to evaluate.
  * You want to visually separate and give equal weight to each choice, such as in template selection.

Keep in mind:

* The card works well here when users are making considered selections — like choosing data with context about what each one does — rather than quickly ticking off a list.
* Don't use the card variant for long lists of options. Cards imply each item deserves attention; if there are more than \~4-5 options, the layout becomes unwieldy and plain checkboxes with good labels will serve better.

## Often used with

[Label](/cdf/aura/primitives/label) per control or group legend; [Helper text](/cdf/aura/primitives/helper-text) for the group; [Card](/cdf/aura/primitives/card) variant when options need descriptions.

## Visual examples

The examples below are interactive and follow the doc site's theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

### With description

Add a description below the Checkbox label when the option needs extra context—for example, explaining what enabling a setting changes or what data is included in a selection.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-checkbox--with-description" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-checkbox--with-description&viewMode=story&globals=theme:light" title="Checkbox with description story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Horizontal

Lay out a Checkbox group horizontally when options are short and few—such as visibility toggles or column filters—so users can scan and compare choices in a single row.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-checkbox--horizontal" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-checkbox--horizontal&viewMode=story&globals=theme:light" title="Checkbox horizontal story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Card

Use the Checkbox card variant when each option needs a title and description—for example, choosing a plan tier or feature set where users should evaluate options side by side.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-checkbox--card" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-checkbox--card&viewMode=story&globals=theme:light" title="Checkbox card story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Horizontal cards

Arrange Checkbox cards in a horizontal row when you have two to four distinct options that each deserve equal visual weight, such as selecting a data source or export format.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-checkbox--horizontal-cards" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-checkbox--horizontal-cards&viewMode=story&globals=theme:light" title="Checkbox horizontal cards story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Disabled

Use a disabled Checkbox when an option is temporarily unavailable, and pair it with helper text or a tooltip that explains why the user cannot select it.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-checkbox--disabled" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-checkbox--disabled&viewMode=story&globals=theme:light" title="Checkbox disabled story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### States

Reference the Checkbox states example to confirm checked, unchecked, and indeterminate visuals render correctly—especially in parent-child groups where partial selection is common.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-checkbox--states" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-checkbox--states&viewMode=story&globals=theme:light" title="Checkbox states story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## Accessibility

* Label association: Programmatically connect custom box primitives to label text using matching `id` and `htmlFor` properties.
* Keyboard and ARIA: Support Space key toggling natively. Set `role="checkbox"` and verify `aria-checked` accurately reflects true, false, or `"mixed"` (indeterminate) states.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-checkbox--accessibility" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-checkbox--accessibility&viewMode=story&globals=theme:light" title="Checkbox accessibility story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>