Checkbox
Checkbox is a native <input type="checkbox"> with a styled box, wrapped in a <label> so the text toggles it too.
Each checkbox controls its own boolean; several can be on at once.Forms
When to use
Use when
- Accepting terms or setting independent preferences in a form submitted later.
- Picking zero, one or several items of a short list.
Avoid when
- Only one option of a set may be chosen — use
Radio. - The setting takes effect immediately — use
Switch. - You render several from data — use
FieldGroup.
Usage
<Checkbox name="terms" label="I accept the terms" checked={accepted} onChange={(e) => setAccepted(e.target.checked)} />
<Checkbox name="news" label="Send me news" defaultChecked />
<Checkbox name="locked" label="Disabled" disabled />Color and states
<Checkbox name="filter" label="Only favorites" color="information" /> <Checkbox name="consent" label="Consent" variant="error" />
The checked fill uses color (default primary). A validation variant (success, error) wins over color.
indeterminate shows the mixed state of a partly selected parent. The prop is the source of truth: a click fires
onChange, and the box stays mixed until you set indeterminate={false}.
Label
A string label renders as small text in ink.primary; labelProps overrides its typography. A ReactNode
label (a link, bold text) renders as-is and ignores labelProps.
<Checkbox name="terms" label="I have read the terms" labelProps={{ fontSize: 'micro', color: 'ink.secondary' }} />Accessibility
- The native input takes focus with
Taband toggles withSpace. - Keyboard focus draws a
:focus-visibleoutline on the box, kept in forced-colors mode. - A checkbox with no visible
labelneeds anaria-label. indeterminateis announced as mixed.
Properties
Name
Type
Default
Description
color"primary""secondary""tertiary""information""success""warning""danger"'primary'Interaction palette of the checked state (fill / ring / ink). Defaults
to the brand `primary`, like `Button` and `Tabs`. `variant` (`success` /
`error`) still wins when set.
indeterminatebooleanfalseMixed state — a dash on the checked fill, announced as `mixed` by
assistive technology (native `indeterminate` property). For a parent
whose children are only partly selected. The prop is the source of
truth: a click fires `onChange`, and the box stays mixed until you set
it to `false` from your state.
labelReactNodenoneText or element displayed next to the box. When a `string`, it is rendered
via `BaseText`; when a `ReactNode`, it is rendered as-is.
labelPropsPartial<TextInterface>noneTypography overrides for a string `label` (`fontSize`, `color`, …).
Ignored when `label` is a `ReactNode`.
@example ```tsx
<Checkbox name="terms" label="Aceito" labelProps={{ fontSize: 'micro', color: 'ink.secondary' }} />
```
onChange((e: ChangeEvent<HTMLInputElement, Element>) => void)nonerefRef<HTMLInputElement>noneRef to the native `<input type="checkbox">` (React 19 ref-as-prop).
valuestringnonevariant"success""default""error"'default'Visual variant of the input — reflects the validation state.
Placement props (area, alignSelf, justifySelf) apply to the label wrapper.