Checkbox
Checkboxes are most commonly used to give merchants a way to make a range of selections (zero, one, or multiple). They may also be used as a way to have merchants indicate they agree to specific terms and services.
Props
No props found for this component, run `yarn gen:docs` to generate component meta first.
Slots
No slots found for this component, run `yarn gen:docs` to generate component meta first.
Events
Checkbox events
Best practices
Checkboxes should:
- Work independently from each other. Selecting one checkbox shouldn’t change the selection status of another checkbox in the list. The exception is when a checkbox is used to make a bulk selection of multiple items.
- Be framed positively. For example, say “Publish store” instead of “Hide store”.
- Always have a label when used to activate or deactivate a setting.
- Be listed according to a logical order, whether it’s alphabetical, numerical, time-based, or some other clear system.
- Link to more information or include a subtitle as required to provide more explanation. Don’t rely on tooltips to explain a checkbox.
Content guidelines
Lists with checkboxes
Lists that use checkboxes should:
- Start with a capital letter
- Not use commas or semicolons at the end of each line
- In the rare case where the checkbox is asking merchants to agree to terms or service, use the first person
Related components
- To present a list of options where merchants can only make a single choice, use the radio button component
- To display a list of related content, use the choice list component
- To create an ungrouped list, use the content list component
Accessibility
Screen readers convey the state of the checkbox automatically.
- Use the
disabled
prop to apply the HTMLdisabled
attribute to the checkbox<input>
. This prevents merchants from being able to interact with the checkbox, and conveys its inactive state to assistive technologies. - Use the
id
prop to provide a uniqueid
attribute value for the checkbox. If anid
isn’t provided, then the component generates one. All checkboxes must have uniqueid
values to work correctly with assistive technologies. - Setting
checked="indeterminate"
conveys the state of the checkbox usingaria-checked="mixed"
. - Setting the
ariaControls
prop conveys the ID of the element whose contents or presence are controlled by the checkbox to screen reader users with thearia-controls
attribute.
Labeling
- The required
label
prop conveys the purpose of the checkbox to all merchants - Use the
labelHidden
prop to visually hide the label but make it available to assistive technologies - When you provide help text via the
helpText
prop or an inline error message via theerror
prop, the help or error content is conveyed to screen reader users with thearia-describedby
attribute
Keyboard support
- Move focus to each checkbox using the tab key (or shift + tab when tabbing backwards)
- To interact with the checkbox when it has keyboard focus, press the space key