Checkbox

v1.0.0 | View in Storybook

​

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 buttons instead.
• The options are part of a form and don’t need to be presented all at once—consider Select.
• The action is immediate and toggles a setting on/off. Use 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 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 per control or group legend; Helper text for the group; 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.

​

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.

​

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.

​

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.

​

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.

​

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.

​

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.