checkbox-button

A styled checkable input that communicates if an option is being added to a group

Add product

About Checkbox Button

The checkbox button is similar to a checkbox in that it presents a user with a binary choice for an item. However, the only action a user can take is to add (or remove) an entity. When a user clicks the checkbox button, the entity is stored, similar to an ‘add to cart’ experience, until the user saves changes.

The checkbox button is useful for increasing clarity. Since the button only adds or removes entities, the user knows the action they will prompt upon click. The checkbox button also provides a clear visual affordance and a large target to take this action.

Use the add button if the component you’re building:

Exists without other multi-select elements (i.e. checkboxes)
Allows users to select multiple entities
Semantically fits the add/remove model

Structure and Implementation

The checkbox <input> is visually hidden with .slds-assistive-text and a faux checkbox is created using the icon blueprint which allows the display of an icon instead of the standard checkbox.

Click and tap events are captured by a <label> that encases the entire blueprint. The for attribute of your <label> must match the id attribute of your <input>.

The states of the checkbox button are styled with the following classes:

Class	State	Description
`.slds-checkbox-button_is-checked`	checked	The checked state when the checkbox button has been selected
`.slds-checkbox-button_is-disabled`	disabled	The disabled state when the checkbox button has been disabled
`.slds-checkbox-button_is-focused`	focused	The focused state when the checkbox button has focus; important for accessibility

When implementing this blueprint, monitor the state of the checkbox <input> and apply the appropriate state class listed in the above chart based on the current state of the checkbox <input>.

It is possible to change the icon used within the checkbox button, see Different Icons for more details.

Mobile

On mobile devices, such as phones and other devices that have touch as the primary method of interaction, checkbox buttons will have an increased size to accommodate tapping with a finger instead of the more precise mouse cursor.
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 the appropriate context. 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.

Select a device to set the width of the example

Base

Add product

<label class="slds-checkbox-button" for="example-unique-id-4">
  <input type="checkbox" class="slds-assistive-text" id="example-unique-id-4" value="example-unique-id-4" />
  <span class="slds-icon_container slds-icon-utility-add slds-current-color" title="Description of icon when needed">

States

Checked

Add product

<label class="slds-checkbox-button slds-checkbox-button_is-checked" for="example-unique-id-7">
  <input type="checkbox" class="slds-assistive-text" id="example-unique-id-7" value="example-unique-id-7" checked="" />
  <span class="slds-icon_container slds-icon-utility-check slds-current-color" title="Description of icon when needed">

Disabled

Add product

<label class="slds-checkbox-button slds-checkbox-button_is-disabled" for="example-unique-id-10">
  <input type="checkbox" class="slds-assistive-text" id="example-unique-id-10" value="example-unique-id-10" disabled="" />
  <span class="slds-icon_container slds-icon-utility-add slds-current-color" title="Description of icon when needed">

Checked and Disabled

Add product

<label class="slds-checkbox-button slds-checkbox-button_is-checked slds-checkbox-button_is-disabled" for="example-unique-id-13">
  <input type="checkbox" class="slds-assistive-text" id="example-unique-id-13" value="example-unique-id-13" disabled="" checked="" />
  <span class="slds-icon_container slds-icon-utility-check slds-current-color" title="Description of icon when needed">

Examples

Different Icon

You may change the utility icon used by the checkbox button depending on the action you are communicating. Reference the utility icon listing for all available options.

This example is using the recycle_bin_empty utility icon as its base state and the recycle_bin_full utility icon as its checked state.

Add product

<label class="slds-checkbox-button" for="example-unique-id-16">
  <input type="checkbox" class="slds-assistive-text" id="example-unique-id-16" value="example-unique-id-16" />
  <span class="slds-icon_container slds-icon-utility-recycle_bin_empty slds-current-color" title="Description of icon when needed">

Add product

<label class="slds-checkbox-button slds-checkbox-button_is-checked" for="example-unique-id-19">
  <input type="checkbox" class="slds-assistive-text" id="example-unique-id-19" value="example-unique-id-19" checked="" />
  <span class="slds-icon_container slds-icon-utility-recycle_bin_full slds-current-color" title="Description of icon when needed">