Checkbox

Used standalone or part of a Checkbox Group. Standalone, it suits a single option like an email opt-in or terms acceptance. In a Checkbox Group, it suits selecting multiple options like filters.

Use Checkbox...

  • When the option can be selected independently from a group.
  • For standalone agreements, opt-ins, and settings.
  • If there is an indeterminate state to express when only a portion of the option group is selected.

Don't use Checkbox...

  • For related multi-select choices. Use Checkbox Group instead.
  • When the user must choose exactly one option from a related set. Use Radio Group instead.
  • To prompt users to choose between two mutually exclusive options that always has a default value, like “on” or “off”. Use Toggle Switch instead.

The preview has been updated.

Skin

Favorite

Use skin="favorite" to display the Checkbox as a heart shape. Ensure you pass a localized aria-label.

The preview has been updated.

Use instant to remove the animation, for cases where such an animation would be distracting.

The preview has been updated.

Disabled

Use disabled to prevent the option from being checked or unchecked. This will apply in both standalone and Checkbox Group usages.

The preview has been updated.

Indeterminate

Use indeterminate to show a dash that summarizes the mixed selection state of a corresponding Checkbox Group. Refer to the Checkbox Group > Guidelines > Indeterminate guidelines for a full example.

The preview has been updated.

Legacy API

Prior to SWAN v3.44.0, the Checkbox component did not support children, and required a separate, manually linked non-FormField label. This API is still supported to ease migration efforts, but we recommend passing children directly to the component which now renders as a aria-labelledby associated div automatically. When used in this manner, the component also requires a value.

The preview has been updated.

Labels, errors, and helper text

Use the FormField components to add a label, error message, or helper text to a standalone Checkbox. They apply the necessary ARIA attributes for you, so you don't need to add them yourself. Use a clear label that describes the action or state controlled by the Checkbox.

Managing State

Controlled

Use checked to provide a stored boolean and onChange to provide a callback for managing that boolean. The callback will be invoked whenever the Checkbox is clicked by the user.

The preview has been updated.

Uncontrolled

Omit checked to allow the browser to manage the state. Optionally, use defaultChecked to set the initially selected values, and/or pass onChange to react to changes (for example, to track the selection) without taking over the state.

The preview has been updated.

Checkbox Group

For grouping multiple Checkboxes, refer to the Checkbox Group guidelines.

Accessibility

By default, a Checkbox is named by its contents, so rich contents (e.g. a product name, price, callout) become a long, cluttered name to a screen reader.

To override the default name with a short custom one, use aria-label or aria-labelledby to reuse text from another element (see Accessibility guidelines). If you set both, aria-label wins. The Checkbox’s full contents then become its description (using aria-describedby), so it stays easy to identify without losing information.

Props

See core props for additional props that can be applied to each of these components. Each component also accepts the React-equivalent native HTML attributes of the element it renders, unless a listed prop replaces one or a note says otherwise.
Checkbox
Renders <input>. With content, renders a div; the ref and input attributes target its inner input.
proptyperequireddefault
name
The `name` submitted with a form, when used standalone. Has no effect inside a `CheckboxGroup`, which sets the name for all of its options from its own `name` prop.
string
false
null
defaultChecked
Whether the checkbox starts checked, when used standalone and uncontrolled. Has no effect inside a `CheckboxGroup`, which controls it from its own `defaultSelectedValues`.
boolean
false
null
value
A string representing the value of this choice.
stringnumberreadonly string[]
false
null
checked
Whether the checkbox is checked, when used standalone and controlled. Has no effect inside a `CheckboxGroup`, which controls it from its own `selectedValues`.
boolean
false
null
skin
The visual style of the Checkbox.
"standard""favorite"null
false
standard
instant
If set to true, the checkbox will animate instantly.
booleannull
false
false
indeterminate
An indeterminate checkbox means that its state is unclear. Typically, this is used when the checkbox has some sub-options under it.
booleannull
false
false

Related