Skip to main content

Checkbox

note

There are deprecated versions of this component. Switch to a version of the docs older than 10.0.x to view their docs.

Examples

Check out the Usage section for details about how and when to use the Checkbox and CheckboxGroup components.

Basic checkbox

The Checkbox component can be used alone, outside of the CheckboxGroup context.

<Checkbox label="This is a single checkbox" />

Basic checkboxes in checkbox group

The CheckboxGroup component acts as container for a set of Checkbox elements. You can choose to display or hide the label, but it is mandatory for the component's accessibility.

<CheckboxGroup label="This is a group">
<Checkbox label="option 1" />
<Checkbox label="option 2" />
</CheckboxGroup>

Group without label

You can hide the CheckboxGroup label by setting the hideLabel property to true. This does not affect any of the other behaviors of the CheckboxGroup element.

<CheckboxGroup
label="This is only for aria-label"
hideLabel={true}>
<Checkbox label="option 1" />
<Checkbox label="option 2" />
</CheckboxGroup>

Horizontal group

CheckboxGroup allows the display of options in horizontal distribution by setting the horizontal property to true.

<CheckboxGroup
label="This is an horizontal group"
horizontal={true}>
<Checkbox label="option 1" />
<Checkbox label="option 2" />
</CheckboxGroup>

Checkbox and CheckboxGroup messages

Both components allow developers to show error messages. When set at the CheckboxGroup level, errors are displayed below all options. However, when set at the Checkbox level inside a CheckboxGroup, the message is ignored and has no effect.

  export function CheckboxMessages() {
const [validationMessages, setValidationMessages] = useState({});
const [groupValidationMessages, setGroupValidationMessages] = useState({});

const onChange = useCallback((e, newChecked) => {
setValidationMessages({});
setGroupValidationMessages({});

if (newChecked) {
setValidationMessages({ error: ['This is ignored'] });
setGroupValidationMessages({ error: ['Only second checkbox can be marked'] });
}
}, []);

return (
<CheckboxGroup
label="Do not select the forbidden option"
stateMessages={groupValidationMessages}
>
<Checkbox
label="Forbidden option"
onChange={onChange}
stateMessages={validationMessages}
/>
<Checkbox label="You can select this one" />
</CheckboxGroup>
);
}
}

Indeterminate state

Although this is not implemented as part of the Checkbox component, the native behavior of an HTML input element is available. In this case, the indeterminate state can be set programmatically through JavaScript. A checkbox in the indeterminate state has a horizontal line in the box, instead of a check or tick. In the example below, the style is modified to make the option visible.

export function SetIndeterminateState() {
const onChange = useCallback((e, newCheck) => {
(document.getElementById('checkbox2') as HTMLInputElement).indeterminate =
newCheck;
}, []);

const style = { opacity: 100 };

return (
<CheckboxGroup label="Group of checkboxes">
<Checkbox
label="Set the next checkbox as 'indeterminate'"
onChange={onChange}
/>
<Checkbox
label="This is another checkbox"
id="checkbox2"
checked={false}
style={style}
/>
</CheckboxGroup>
);
}