Checkbox
The <Checkbox>
component is a form element that allows users to make a binary choice, either selecting or deselecting an option. Multiple checkboxes can be grouped together using <Checkbox.Group>
to enable the selection of zero, one or any number of options.
It is commonly used in forms, settings, and anywhere users need to make multiple selections or toggle individual options. A <Checkbox>
can also display an indeterminate state to represent a partially selected group.
Anatomy
A checkbox consists of a clickable box and a label. The box has three states: unchecked, checked, or indeterminate. The label, positioned next to the checkbox, describes the option or action associated with it. Users interact with the checkbox by clicking the box or label to toggle between states.
A checkbox group consists of multiple checkboxes, each with its own label, allowing users to select one or more options within a related set.

Appearance
The appearance of a component can be customized using the variant
and size
props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.
Property | Type | Description |
---|---|---|
variant | - | The available variants of this component. |
size | - | The available sizes of this component. |
Usage
Checkboxes are used when there are multiple items to select in a list. Each checkbox works independently from other checkboxes in the list, therefore checking an additional box does not affect any other selections. Users can select zero, one, or any number of items. Checkboxes are commonly used in forms where users need to make multiple selections from a set of options.
Particularly checkboxes are useful in settings where users need to make non-exclusive selections. They provide a clear and straightforward way to toggle options on or off. When used in a group, they can help simplify complex decision-making processes. Additionally, checkboxes can be combined with other form elements.
Number of options
Use checkboxes when there are no more than 10 to 15 options, as too many of them can overwhelm users and clutter the interface. For larger sets of options, refer to the Multiple Selection Pattern for a better user experience.
If a user can select only one option from a list, radio buttons should be used instead, as checkboxes suggest that multiple options can be chosen.

Use checkboxes when you have up to 15 options, and multiple options can be chosen.

Don't use checkboxes when only one item can be selected.
Label Text
We recommend checkbox labels being fewer than three words because shorter checkbox labels improve readability and reduce cognitive load, making it easier for users to quickly understand and select options. This enhances the overall user experience, especially on small screens.
If you are tight on space, consider rewording the label. Do not truncate checkbox label text with an ellipsis. Long labels may wrap to a second line, and this is preferable to truncation.

If the label is long, wrap to a second line.

Do not truncate checkbox label text with an ellipsis.
Checkbox or switch
Use a checkbox when its effect will only occur after the user submits or confirms the selection. Checkboxes are ideal for allowing users to choose options that need to be finalized through submission, such as in a form.
In contrast, use a switch for actions that take effect immediately upon toggling, without requiring further confirmation or submission, making switches more suitable for instant settings changes.

Use checkboxes in forms where the selection will only take effect upon submission.

Don't use a checkbox to toggle a state with immediate effect.
Indeterminate
The indeterminate state of a checkbox is used when a group of related checkboxes is partially selected, meaning some but not all options are chosen. This state visually indicates that the selection is incomplete or mixed.
It’s commonly used in "Select All" scenarios, where selecting only some of the available options triggers the parent checkbox to show an indeterminate state, helping users understand that not all choices have been selected.
Props
Checkbox
aria-controls?
string;
aria-describedby?
string;
aria-details?
string;
aria-errormessage?
string;
aria-label?
string;
aria-labelledby?
string;
autoFocus?
boolean;
checked?
boolean;
defaultChecked?
boolean;
disabled?
boolean;
"false"
error?
boolean;
true
, the checkbox is considered invalid and if set the errorMessage
is shown instead of the description
."false"
excludeFromTabOrder?
boolean;
id?
string;
indeterminate?
boolean;
"false"
inputRef?
RefObject<HTMLInputElement | null>;
label?
ReactNode;
name?
string;
onBlur?
(e: FocusEvent<Element, Element>) => void;
onChange?
(isSelected: boolean) => void;
onFocus?
(e: FocusEvent<Element, Element>) => void;
onFocusChange?
(isFocused: boolean) => void;
onHoverChange?
(isHovering: boolean) => void;
onHoverEnd?
(e: HoverEvent) => void;
onHoverStart?
(e: HoverEvent) => void;
onKeyDown?
(e: KeyboardEvent) => void;
onKeyUp?
(e: KeyboardEvent) => void;
readOnly?
boolean;
"false"
ref?
Ref<HTMLLabelElement>;
ref.current
to null
(or call the ref with null
if you passed a callback ref).
@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}required?
boolean;
"false"
slot?
string | null;
null
value indicates that the local props completely override all props received from a parent.validate?
(value: boolean) => true | ValidationError | null;
validationBehavior="native"
. For realtime validation, use the isInvalid
prop instead.validationBehavior?
"native" | "aria";
'native'
value?
string;
Checkbox.Group
aria-describedby?
string;
aria-details?
string;
aria-errormessage?
string;
aria-label?
string;
aria-labelledby?
string;
children?
ReactNode;
defaultValue?
string[]
description?
ReactNode;
disabled?
boolean;
"false"
error?
boolean;
true
, the checkbox is considered invalid and if set the errorMessage
is shown instead of the description
."false"
errorMessage?
ReactNode | ((v: ValidationResult) => ReactNode);
id?
string;
label?
ReactNode;
name?
string;
onBlur?
(e: FocusEvent<Element, Element>) => void;
onChange?
(value: string[]) => void;
onFocus?
(e: FocusEvent<Element, Element>) => void;
onFocusChange?
(isFocused: boolean) => void;
orientation?
AlignmentProp;
"vertical"
readOnly?
boolean;
"false"
required?
boolean;
"false"
slot?
string | null;
null
value indicates that the local props completely override all props received from a parent.validate?
(value: string[]) => true | ValidationError | null;
validationBehavior="native"
. For realtime validation, use the isInvalid
prop instead.validationBehavior?
"native" | "aria";
'native'
value?
string[]
width?
WidthProp;
"full"
Alternative components
Choosing the right alternative to checkbox is important for providing an optimal user experience, especially when different types of selections are required. Depending on the nature of the choices and the desired interaction, the following components can serve as an alternative to checkboxes:
- Switch: When there is only on option that should have an immediate effect.
- Radio: When only one option can be selected from a set, a radio group is an alternative to a checkbox group, as radio buttons restrict the selection to a single option.
- SelectList: When you need more than just a text label to represent options, a
<SelectList>
can be used instead. - TagGroup: When you want to visually highlight selected options as individual tags or want a horizontal list of options, use the
<Tag>
component.