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:

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 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#

<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">
    <svg class="slds-icon slds-icon_x-small" aria-hidden="true">

States#

Checked#

<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">
    <svg class="slds-icon slds-icon_x-small" aria-hidden="true">

Disabled#

<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">
    <svg class="slds-icon slds-icon_x-small" aria-hidden="true">

Checked and Disabled#

<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">
    <svg class="slds-icon slds-icon_x-small" aria-hidden="true">

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.

<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">
    <svg class="slds-icon slds-icon_x-small" aria-hidden="true">

<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">
    <svg class="slds-icon slds-icon_x-small" aria-hidden="true">