Checkbox
- HTML/CSS:Dev Ready
- Web Component:In Progress (1 of 2 variants)
- Layout:Responsive
About Checkbox#
The ability to style checkboxes with CSS varies across browsers. To ensure that checkboxes look the same everywhere, we use a custom DOM. Pay close attention to the markup, because all elements must exist for the styles to work.
Accessibility#
Groups of checkboxes should be marked up using the fieldset and legend element. This helps someone using assistive technology to understand the question they're answering with the group of checkboxes. The fieldset is placed around the whole group and the legend contains the question.
Custom checkboxes are created by applying the .slds-checkbox class to a <label> element. To remain accessible to all user agents, place <input> with type="checkbox" inside the <label> element. The <input> is then visually hidden, and the styling is placed on a span with the .slds-checkbox_faux class. The styling of the span changes based on whether the checkbox is selected or focused by using a pseudo-element. A second span with .slds-form-element__label contains the label text.
When a single checkbox is required, <div class="slds-checkbox"> should get <abbr class="required" title="required">*</abbr> added to the DOM, directly before the <input type="checkbox" /> for visual indication that the checkbox is required.
When a checkbox group is required, the <fieldset> should receive the class .slds-is-required. The <legend> should then get <abbr class="required" title="required">*</abbr> added to the DOM for visual indication that the checkbox group is required.
As SLDS checkboxes rely on the :checked pseudo selector, and the indeterminate state is only accessible via JavaScript, the use of a CSS class on the input will be necessary to implement this in SLDS. Use JavaScript to add the class when the indeterminate property is set to true on the input.
Mobile#
On mobile devices, such as phones and other devices that have touch as the primary method of interaction, checkboxes will have an increased size to accommodate tapping with a finger instead of the more precise mouse cursor, as well as having larger label text.
Below is a live example of what to expect in that context. No code changes are needed in the Salesforce platform context as this change occurs automatically in Salesforce native mobile applications. For those users not on the Salesforce platform, these modifications will occur automatically when the secondary touch stylesheet is loaded and the device has touch as the primary method of interaction.
Base#
The base variant of a checkbox is a single boolean value. The base checkbox is consumed by both a grouped checkbox and a checkbox within a form element.
The form element variant accommodates a top level label and additional functionality such as like help text and read only mode. Help text is not supported on a single checkbox.
<div class="slds-form-element">
<div class="slds-form-element__control">
<div class="slds-checkbox">
<input type="checkbox" name="options" id="checkbox-unique-id-4" value="checkbox-unique-id-4" checked="" />States#
Required#
<div class="slds-form-element">
<div class="slds-form-element__control">
<div class="slds-checkbox">
<abbr class="slds-required" title="required">*</abbr>Error#
<div class="slds-form-element slds-has-error">
<div class="slds-form-element__control">
<div class="slds-checkbox">
<abbr class="slds-required" title="required">*</abbr>Disabled#
<div class="slds-form-element">
<div class="slds-form-element__control">
<div class="slds-checkbox">
<input type="checkbox" name="options" id="checkbox-unique-id-13" value="checkbox-unique-id-13" disabled="" />Checked#
<div class="slds-form-element">
<div class="slds-form-element__control">
<div class="slds-checkbox">
<input type="checkbox" name="options" id="checkbox-unique-id-16" value="checkbox-unique-id-16" disabled="" checked="" />Examples#
Group#
<fieldset class="slds-form-element">
<legend class="slds-form-element__legend slds-form-element__label">Checkbox Group Label</legend>
<div class="slds-form-element__control">
<div class="slds-checkbox">Required#
<fieldset class="slds-form-element">
<legend class="slds-form-element__legend slds-form-element__label">
<abbr class="slds-required" title="required">*</abbr> Checkbox Group Label</legend>
<div class="slds-form-element__control">Error#
<fieldset class="slds-form-element slds-has-error">
<legend class="slds-form-element__legend slds-form-element__label">
<abbr class="slds-required" title="required">*</abbr> Checkbox Group Label</legend>
<div class="slds-form-element__control">Disabled#
<fieldset class="slds-form-element">
<legend class="slds-form-element__legend slds-form-element__label">Checkbox Group Label</legend>
<div class="slds-form-element__control">
<div class="slds-checkbox">RTL (right to left direction)#
<div dir="rtl">
<div class="slds-form-element">
<div class="slds-form-element__control">
<div class="slds-checkbox">Form Element#
<div class="slds-form-element">
<label class="slds-form-element__label" for="checkbox-unique-id-46">Form Element Label</label>
<div class="slds-form-element__control">
<span class="slds-checkbox slds-checkbox_standalone">States#
Checked#
<div class="slds-form-element">
<label class="slds-form-element__label" for="checkbox-unique-id-49">Form Element Label</label>
<div class="slds-form-element__control">
<span class="slds-checkbox slds-checkbox_standalone">Disabled#
<div class="slds-form-element">
<label class="slds-form-element__label" for="checkbox-unique-id-52">Form Element Label</label>
<div class="slds-form-element__control">
<span class="slds-checkbox slds-checkbox_standalone">Checked and Disabled#
<div class="slds-form-element">
<label class="slds-form-element__label" for="checkbox-unique-id-55">Form Element Label</label>
<div class="slds-form-element__control">
<span class="slds-checkbox slds-checkbox_standalone">Error#
<div class="slds-form-element slds-has-error">
<label class="slds-form-element__label" for="checkbox-unique-id-58">
<abbr class="slds-required" title="required">* </abbr>Form Element Label</label>
<div class="slds-form-element__control">Required#
<div class="slds-form-element">
<label class="slds-form-element__label" for="checkbox-unique-id-61">
<abbr class="slds-required" title="required">* </abbr>Form Element Label</label>
<div class="slds-form-element__control">View mode#
View mode is the read only state of a checkbox form element.
Unchecked#
<div class="slds-form-element slds-form-element_readonly">
<span class="slds-form-element__label">Form Element Label</span>
<div class="slds-form-element__control">
<span class="slds-icon_container slds-icon-utility-steps slds-current-color" title="False">Checked#
<div class="slds-form-element slds-form-element_readonly">
<span class="slds-form-element__label">Form Element Label</span>
<div class="slds-form-element__control">
<span class="slds-icon_container slds-icon-utility-check slds-current-color" title="True">Examples#
With help text#
<div class="slds-form-element">
<label class="slds-form-element__label" for="checkbox-unique-id-64">Form Element Label</label>
<div class="slds-form-element__icon">
<button class="slds-button slds-button_icon">Required with help text#
<div class="slds-form-element">
<label class="slds-form-element__label" for="checkbox-unique-id-67">
<abbr class="slds-required" title="required">* </abbr>Form Element Label</label>
<div class="slds-form-element__icon">Required with help text with tooltip#
<div style="padding-top:3rem">
<div class="slds-form-element">
<label class="slds-form-element__label" for="checkbox-unique-id-70">
<abbr class="slds-required" title="required">* </abbr>Form Element Label</label>Styling Hooks Overview#
Use these CSS Custom Properties as hooks to customize this SLDS component with your own style. For more information, read the technical documentation.
| Category | Styling Hook Name | Value Type(s) | Fallback Value |
|---|---|---|---|
| Box Shadow | --sds-c-checkbox-shadow | String | |
--sds-c-checkbox-shadow-focus | String | 0 0 3px #0176d3 | |
| Color | --sds-c-checkbox-color-border | Color | #dddbda |
--sds-c-checkbox-color-background | Color | white | |
--sds-c-checkbox-color-border-checked | Color | var(--sds-c-checkbox-color-border, #dddbda) | |
--sds-c-checkbox-color-background-checked | Color | var(--sds-c-checkbox-color-background, white) | |
--sds-c-checkbox-mark-color-foreground | Color | #0176d3 | |
--sds-c-checkbox-color-border-focus | Color | #1b96ff | |
| Radius | --sds-c-checkbox-radius-border | Dimension | 0.125rem |
Overview of CSS Classes#
- Selector
- The CSS class being referred to.
- Summary
- A description of what the class does.
- Support
- Whether the class name is dev-ready (meaning it's fully vetted and tested and safe to use) or prototype (which means it's not fully vetted yet).
- Restrict
- The selector that the class name is allowed to be used on.
- Variant
- The base level pattern for a component. A variant can be extended to create another variant of that component, for example, a stateful button is a derivative of the base button.
- Modifier
- A single class that can be added to an HTML element of a component to modify its output. Typically these will be colors, sizing and positioning.
| Selector | .slds-checkbox |
|---|---|
| Summary | Initializes checkbox |
| Support | dev-ready |
| Restrict | span, label, div |
| Variant | True |
| Selector | .slds-checkbox_stackedDeprecated |
|---|---|
| Summary | stacks label over checkbox |
| Restrict | .slds-checkbox |
| Modifier | True |
| Selector | .slds-checkbox_faux |
|---|---|
| Summary | Creates a custom styled checkbox |
| Restrict | .slds-checkbox span |
| Selector | .slds-checkbox__label |
|---|---|
| Summary | Container for faux checkbox, text, and slds-form-element__label |
| Restrict | .slds-checkbox label |
| Selector | .slds-checkbox_standalone |
|---|---|
| Summary | Checkbox with top-level label and value != label |
| Support | dev-ready |
| Restrict | .slds-checkbox |
| Variant | True |
Checkbox Release Notes
2.14.0
Added
- Enabled styling hooks for checkbox. See checkbox's styling hooks overview table for a full listing of the currently available hooks.
2.11.5
Added
- Added documentation and examples for mobile/touch context
2.10.0
Changed
- For touch devices:
- Increase size of faux checkbox to
$square-tappable-x-small(1.5rem) - Increase tap target size of
.slds-checkbox__labelto$height-tappable(2.75rem) and center with flex properties - Increase
font-sizeof inline label to$font-size-5(1rem) - Increase size of
.slds-checkbox_standaloneto$height-tappable(2.75rem) for consistency with tap target size increases - Within
.slds-checkbox_standalone, increase the tap target size of the checkbox input
- Increase size of faux checkbox to
- Ensure the checkbox input is hidden with
opacity: 0
2.9.0
Fixed
- Added @noflip annotation for correct alignment in RTL languages
2.8.0
Added
- Added unchecked image based checkbox example view mode checkbox - unchecked
- Added checked image based checkbox example view mode checkbox - checked
2.7.0
Added
- Added variant for a checkbox inside of a standard form element component
Fixed
- Fixed issue #556 by increasing the font size on checkbox labels to match radio button labels