A checkbox form element represents a boolean option.


Checkbox states
Loading story...
Checkbox tree
Loading story...

View in Pajamas UI Kit →


Numbered diagram of a checkbox structure
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.


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 combobox instead.


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


  • 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.


  • Selecting an option changes it state to either checked or unchecked.
  • Selecting a child checkbox can change the state of a parent checkbox to either checked, unchecked, or indeterminate depending on the state of sibling checkboxes.
  • Selecting the parent checkbox to either checked or unchecked, all children checkboxes must match its state.


  • 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.


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

Last updated at: