CheckboxGroup

A checkbox group handles the spacing and orientation for a grouping of checkboxes, as well as providing a label.

AI Tip Want to skip the docs? Use the MCP Server

Anatomy

Structure

<CheckboxGroup>
    <Checkbox /> /* (Required) A checkbox within the group */
</CheckboxGroup>

Composed Components

A CheckboxGroup uses the following components:

Checkbox

Checkboxes are used for multiple choices, not for mutually exclusive choices. Each checkbox works independently from other checkboxes in the list, therefore checking an additional box does not affect any other selections.

Usage

Read-only

A checkbox group can be read-only.

Disabled

A checkbox group can be disabled.

Invalid

A checkbox group can be invalid.

Sizes

A checkbox group can vary in size.

No Label

A checkbox group can be rendered without a label.

Description

A checkbox group can have a description to provide more information to the user.

Bordered

A checkbox group can be bordered.

Orientation

A checkbox group can have a different orientation.

Fluid

A checkbox group can be expanded to full width to fill its parent container.

Controlled

A checkbox group can handle value state in controlled mode.

Description on Items

A checkbox can have a description to provide more information to the user.

ContextualHelp

A ContextualHelp element may be placed next to the label to provide additional information or help about a CheckboxGroup.

Best Practices

Checkboxes should:

Work independently from each other. Selecting one checkbox should not change the selection status of another checkbox in the list. The exception is when a checkbox is used to make a bulk selection of multiple items.
Be framed positively.
Always have a label when used to activate or deactivate a setting.
Be listed according to a logical order, whether it's alphabetically, numerical, time-based, or some other clear system.
Link to more information or include a helper text as required to provide more explanation. Don't rely on tooltips to explain a checkbox.

You can use checkboxes in many situations, such as:

Forms: that can be in a full-page layout, in a modal or a panel.
Filtering and batch action: to filter data either on a page, in a menu, or within a component. Checkboxes can be used in Tables for batch editing purposes.
Tiles: to perform a selection over a collection of tiles that are related to one another.

Alignment

Checkbox labels are positioned to the right of their inputs. If there is a checkbox grouping, they can be laid out vertically. When possible, arrange the checkbox and radio button groups vertically for easier reading.

Placement

The checkbox component is often used in forms. Forms can be placed on a full page, in a modal or in a side panel. A checkbox can also be used for agreeing to terms and conditions or to filter information. Checkboxes in a form should be placed at least 24px below of before the next component. There's a space of 8px between each checkbox within a grouping.

Overflow content

We recommend checkbox labels being fewer than three words. 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 than truncation. The text should wrap beneath the checkbox so the control and label are top aligned.

Checkbox vs. Switch

Checkbox and Switch components are very similar in term of results when used in a form. However, a few details tell them apart.

Checkbox component can offer multiple options to the user, while the Switch only offers one.
Users can select none to any option with checkboxes, while the Switch always have one active selection at all time (either “on” or “off” position)
Choices offered in checkbox grouping are independant from each other, while the Switch's mutually exclusive.
The Switch's selection takes effect immediately, while the checkbox only happens once the user applied the change.

Props

listProps?

The props of the list element that wraps the Checkbox components.

orientation?

A CheckboxGroup can be displayed horizontally or vertically.

Defaults to vertical.

variant?

A CheckboxGroup has two variants: borderless and bordered.

Defaults to borderless.

isFluid?

If true, the CheckboxGroup will take all available width.

Defaults to false.

form?

The element to associate the input with. The value of this attribute must be the id of a in the same document. See MDN.

style?

The inline style for the element. A function may be provided to compute the style based on component state.

children?

The children of the component. A function may be provided to alter the children based on component state.

validationBehavior?

Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

Defaults to 'native'.

name?

The name of the input element, used when submitting an HTML form. See MDN.

value?

The current value (controlled).

defaultValue?

The default value (uncontrolled).

isDisabled?

Whether the input is disabled.

isReadOnly?

Whether the input can be selected but not changed by the user.

isRequired?

Whether user input is required on the input before form submission.

isInvalid?

Whether the input value is invalid.

validate?

A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.

className?

The CSS className for the element. A function may be provided to compute the class based on component state.

dir?

lang?

inert?

translate?

description?

The helper message of the field.

errorMessage?

The error message of the field.

label?

The label of the field.

necessityIndicator?

Whether the required state should be shown as an asterisk or a label, which would display (Optional) on all non required field labels.

size?

A Field can vary in size.

Defaults to md.

contextualHelp?

A ContextualHelp element to place next to the label.

Migration Notes

Coming from Orbiter, you should be aware of the following changes:

onChange signature has been changed – no events are passed.
disabled has been renamed to isDisabled.
required has been renamed to isRequired.
fluid has been renamed to isFluid.
reverse is not supported, use flex-direction or row-reverse instead.
autofocus is not supported. You must put autofocus on the actual Checkbox.
The default orientation is now vertical instead of horizontal.
validationState is removed. use isInvalid instead. There is no isValid.
wrap is removed. If horizontal, radios will wrap.
There is no align prop. If needed, the styled system can be used.
The inline prop is not available.