Checkbox

A checkbox form element represents a boolean option.

Examples

Checkbox states
Checkbox tree

View in Pajamas UI Kit →

Structure

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.

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

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.
  • When using GlFormGroup, the label prop alone does not give the input an accessible name.
  • The label-for prop must also be provided to give the input an accessible name.

Single checkbox

Single checkbox with label
<gl-form-checkbox v-model="status" value="task-complete">
  {{ __('Task complete') }}
</gl-form-checkbox>
Single checkbox with hidden label
<gl-form-checkbox v-model="status" value="task-complete">
  <span class="gl-sr-only">{{ __('Task complete') }}</span>
</gl-form-checkbox>

Multiple checkboxes

Multiple labeled checkboxes grouped within a fieldset
<gl-form-group :label="__('Task list')">
  <gl-form-checkbox value="task-1">{{ __('Task 1') }}</gl-form-checkbox>
  <gl-form-checkbox value="task-2">{{ __('Task 2') }}</gl-form-checkbox>
</gl-form-group>

Using GlFormCheckboxGroup:

<gl-form-group :label="__('Task list')">
  <gl-form-checkbox-group v-model="selected" :options="options" />
</gl-form-group>
Multiple labeled checkboxes grouped within a fieldset with hidden legend
<gl-form-group :label="__('Task list')" label-sr-only>
  <gl-form-checkbox value="task-1">{{ __('Task 1') }}</gl-form-checkbox>
  <gl-form-checkbox value="task-2">{{ __('Task 2') }}</gl-form-checkbox>
</gl-form-group>

Using GlFormCheckboxGroup:

<gl-form-group :label="__('Task list')" label-sr-only>
  <gl-form-checkbox-group v-model="selected" :options="options" />
</gl-form-group>

Last updated at: