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.

View sourceView on npmReport an issueWAI-ARIA

Anatomy

Structure

<Checkbox>
    <IconList /> /* (Optional) A list of icons in the checkbox */
    <Icon /> /* (Optional) An icon in the checkbox */
    <Text /> /* (Optional) Text in the checkbox, required if using an Icon or an IconList */
</Checkbox>

Composed Components

A Checkbox uses the following components:

Icon

An icon component is used to render a custom icon.

IconList

An IconList encapsulates a collection of icons.

Text

A text component is a primitive component matching Hopper's typography type scale.

Usage

No Label

A checkbox can be rendered without a label.

Checked

A checkbox can be checked.

Indeterminate

A checkbox can be indeterminate.

Disabled

A checkbox can be disabled.

Read-only

A checkbox can be read-only.

Invalid

A checkbox can be invalid.

Sizes

A checkbox can vary in size.

Icon

A checkbox can be rendered with an icon or an icon list.

Description

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

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.

Behaviours

States

The checkbox input allows for a series of states: unselected, selected and indeterminate. The default view of a set of checkboxes is have no option selected. Use the indeterminate state when the checkbox contains a sublist of selections, some of which are selected, and some unselected.

Interactions

Users can trigger an item by clicking the checkbox input directly or by clicking the checkbox label. Having both regions interactive create a more accessible click target. The only hover effect when the mouse is placed over the target is a pointer shape change.

Props

Checkbox

size?

A checkbox can vary in size.

Defaults to md.
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'.
isIndeterminate?

Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.

value?

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

defaultSelected?

Whether the element should be selected (uncontrolled).

isSelected?

Whether the element should be selected (controlled).

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.

autoFocus?

Whether the element should receive focus on render.

name?

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

inputRef?

A ref for the HTML input element.

className?

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

CheckboxField

description?

The description of the checkbox field.

isDisabled?

Whether the checkbox field is disabled.

size?

A checkbox field can vary in size.

Defaults to md.
children?

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

className?

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

style?

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

Migration Notes

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

  • onChange signature has been changed (no event are passed).
  • onValueChange has been deleted, use onChange instead.
  • checked has been renamed to isSelected.
  • disabled has been renamed to isDisabled.
  • required has been renamed to isRequired.
  • indeterminate has been renamed to isIndeterminate.
  • defaultIndeterminate prop has been removed.
  • The Counter component is no longer allowed as a specialized slot.
  • reverse is not supported, use flex-direction or row-reverse instead.
  • validationState has been removed. Use isInvalid instead. There is no isValid.
  • Values are not auto-generated when missed.