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.
indeterminate is applied imperatively to the DOM node, which means a freshly mounted or server-rendered Checkbox briefly shows as unchecked before the dash appears.
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
This section applies to standalone Checkbox only. If your Checkbox is part of a Checkbox Group, refer to the Checkbox Group documentation instead.
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
This section applies to standalone Checkbox only. If your Checkbox is part of a Checkbox Group, refer to the Checkbox Group documentation instead.
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.