Skip to content

Checkbox

Selects one or more options, alone or in a labelled group, with indeterminate and invalid states.

betaReact AriaSource
We’ll email you when a claim changes status.

Installation

pnpm add @syntara/react @syntara/tokens
import { Checkbox, CheckboxGroup } from '@syntara/react';

Usage

import { Checkbox, CheckboxGroup } from '@syntara/react';

export function Channels() {
  return (
    <CheckboxGroup label="Notify me by" defaultValue={['email']}>
      <Checkbox value="email">Email</Checkbox>
      <Checkbox value="sms">SMS</Checkbox>
    </CheckboxGroup>
  );
}

Examples

Group

Notify me byChoose at least one.
On devices where you’re signed in.

Horizontal group

Show

Indeterminate

A "select all" parent for a set of options.

Invalid and disabled

Accept the terms to continue.

Accessibility

KeysAction
SpaceToggles the focused checkbox.
TabMoves between checkboxes.
  • Uses a native checkbox input, so forms and assistive tech work without extra ARIA.
  • Each row is at least 24px tall and the whole label is clickable (WCAG 2.5.8).
  • Descriptions are linked with aria-describedby and stay out of the accessible name.
  • Invalid state shows a danger border plus an error message with an icon.

Guidelines

Do

  • Use for independent on/off choices or picking several items from a list.
  • Write labels as positive statements: "Email me about updates".
  • Use a group label that names the question.

Don’t

  • Don't use a checkbox for settings that apply immediately; use a Switch.
  • Don't use checkboxes for mutually exclusive options; use RadioGroup.

API reference

Checkbox

children
ReactNode

The label. Without one, pass aria-label.

description
ReactNode

Help text under the label, linked with aria-describedby.

value
string

Value inside a CheckboxGroup.

isSelected / defaultSelected
boolean

Controlled / uncontrolled state (standalone).

onChange
(isSelected: boolean) => void

Called when toggled.

isIndeterminate
boolean

Shows a dash, e.g. for a partially selected "select all".

Default false

errorMessage
string | ((validation: ValidationResult) => string)

Standalone only (e.g. accepting terms with isRequired). In a group, the group shows errors.

isRequired / isInvalid / isDisabled
boolean

Validation and disabled state.

Default false

CheckboxGroup

label
ReactNode

Group label. Without one, pass aria-label.

description
ReactNode

Help text under the group label.

errorMessage
string | ((validation: ValidationResult) => string)

Shown with an icon when the group is invalid.

value / defaultValue
string[]

Controlled / uncontrolled selected values.

onChange
(value: string[]) => void

Called when the selection changes.

orientation
  • horizontal
  • verticaldefault

Stack options, or lay them out in a wrapping row.

isRequired / isInvalid / isDisabled
boolean

Validation and disabled state for the whole group.

Default false

Tokens

The semantic tokens this component reads, grouped by what they control. Swatches show this site’s theme; change a tenant’s brand and the component follows with no code change.

Colour13
action.primary.bgaction.primary.fgaction.primary.hoverborder.defaultborder.strongfeedback.danger.onSolidfeedback.danger.solidfocus.ringsurface.defaultsurface.sunkentext.defaulttext.disabledtext.subtle
Type2
font.size.mdline-height.normal
Space and size5
control-heightspace.1space.2space.5space.6
Shape1
radius.field
Depth2
shadow.highlightshadow.raised
Motion6
motion.duration.fastmotion.duration.normalmotion.duration.springmotion.easingmotion.easingOutmotion.spring