Skip to main content

Checkbox

Description​

Checkboxes are used when there are lists of options and the user may select any number of choices, including zero, one, or several. This allows a user to select one or more items from a list of options or select preferred settings with a single checkbox.

Default selections can be set by an application as needed.

Checkboxes allow the user to interact with the checkbox or associated label. The label is vertically centered with the checkbox even when the text wraps.

Usage​

Layout​

Allow 32px minimum horizontal space, or 8px minimum vertical space between checkboxes.

When stacking checkboxes in unusually long lists such as left rail filters, combine checkboxes with a multi-select filter to help users more easily find desired options.

Lay out your lists vertically

Try to present your lists vertically, with one choice per line. This rule works both for toggles and checkboxes. If you must lay your options in a horizontal layout with multiple options per line, make sure to space the buttons and ensure that labels connected which choices.

Example to come: checkbox layout do and do not

Nesting​

In nested layouts or tables with multiselect, selecting a parent checkbox selects all its children. If child checkboxes are both checked and unchecked, the parent checkbox is indeterminate.

Example to come: checkbox nesting do and do not

Filter Counts​

When using checkboxes as filters with counts, display counts on a badge and right align the badges.

Example to come: checkbox filters

Best Practices​

Use positive and active wording for checkbox labels, so that it's clear what will happen if the user turns on the checkbox. Likewise, avoid negations such as "Don't send me an email," which would mean the user would have to make a selection in order for something not to happen.

Write checkbox labels so that users know both what will happen if they check a particular box, and what will happen if they leave it unchecked.

Code​

Default Uncontrolled Checkbox​

The Checkbox component is now uncontrolled. It will take a checked prop, but is rendered as defaultChecked.

<Checkbox checked={true} id="check1" label="Default" />

Default Controlled Checkbox​

function ControlledCheckbox() {
  const [checked, setChecked] = useState(false);

  return (
    <Checkbox.Controlled
      onClick={() => setChecked(!checked)}
      onChange={e => console.log(e)}
      checked={checked}
      id="check2"
      label="Default"
    />
  );
}

Disabled Checkbox​

<Checkbox disabled id="check3" label="Disabled" />

Indeterminate Checkbox​

<Checkbox id="check4" label="Indeterminate" className="indeterminate" />

Checkboxes Props​

NameTypeDefaultDescription
checkedboolfalseSets the checked state of the checkbox
classNamestringnullSets a custom class name on the checkbox
disabledboolfalseDisables checkbox and applies disabled styles
labelstringnullSets the label text shown next to the checkbox
namestringnullSets the name attribute of the checkbox to make it unique
requiredboolfalseSets whether or not the checkbox is required
valueanynullSets the value of checkbox when selected
onChangefunctionnullSets the function to be called when a checkbox is checked or unchecked