Checkbox
A checkbox form element represents a boolean option.
Examples
Structure
- Legend (optional): A title for a group of checkboxes.
- Checkbox: The element that provides the visual affordance for the control.
- Label: Text indicating the option.
- 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
withlegend
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
, thelabel
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: