Checkbox

A checkbox form element represents a boolean option.

Examples

Loading story...

View in Pajamas UI Kit →

Structure

Numbered diagram of a checkbox structure
  1. Legend (optional): A title for a group of checkboxes.
  2. Checkbox: The element that provides the visual affordance for the control.
  3. Label: Text indicating the option.
  4. Help text (optional): Used to further clarify an option.

Guidelines

When to use

  • In a form for a user to indicate a selection of one or more options.

When not to use

  • If only one option in a set can be selected, use radio buttons instead.
  • If you are wanting to have a change immediately applied when an option is selected, consider using a toggle instead.
  • If selecting an option would change the state or view of other content, consider using a segmented control instead.
  • If choices exist outside of a form and as a menu of options, use a dropdown instead.

Appearance

  • Options are stacked vertically, with one checkbox per line.

States

  • Unchecked: The option is unselected.
  • Checked: The option is selected and the checked attribute is applied.
  • Indeterminate: Occurs when nested checkboxes under a parent checkbox are in both checked and unchecked states. The indeterminate state can only be programmatically set with Javascript (example).
  • Disabled: Any of the previous states can also be disabled so that the current state can't be changed.

Behavior

  • Selecting an option changes it state to either checked or unchecked.
  • Selecting a nested checkbox can change the state of a parent checkbox to either checked, unchecked, or indeterminate depending on the state of sibling checkboxes.

Content

  • Use a fieldset with legend to group a set of checkboxes with a clear name and purpose.
  • A text label is positioned to the right of the checkbox element (for left-to-right languages), and should be as concise as possible.
  • Help text can be added below the checkbox label or as a paragraph below the group.

Accessibility

  • Some screen readers will announce the contents of the legend before each nested input to maintain context for a user.

Last updated at: