Component Blueprints

Button Icons

information

You are currently viewing a sandbox preview version of Spring ’20 | Go back to Summer ’20

Button icons provide the user with visual iconography that is typically used to invoke an event or action.

About Button Icons#

Button icons are button elements that represent their behavior with an icon instead of text. The button itself should have the classes slds-button and slds-button_icon, while the svg icon has slds-button__icon on it.

Some styling variations require the button to receive additional 'container' classes that remove the button styling and/or add borders. See below for more detail.

Accessibility#

If an icon button doesn’t include a label, use a title attribute to show on hover for sighted users, and a span with class slds-assistive-text to describe the button's action for screen readers.

When using assistive text, the icon element itself should have aria-hidden set to true.

Mobile#

On mobile devices, such as phones and other devices that have touch as the primary method of interaction, 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.

Base#

<button class="slds-button slds-button_icon" title="Settings">
  <svg class="slds-button__icon" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#settings"></use>
  </svg>

Variations#

Brand#

<button class="slds-button slds-button_icon slds-button_icon-brand" title="Search">
  <svg class="slds-button__icon" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>
  </svg>

Inverse#

<div style="padding:0.5rem;background-color:#16325C">
  <button class="slds-button slds-button_icon slds-button_icon-inverse" title="Search">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>

Icon Containers#

Icon containers remove button styling from the button, leaving a bare icon.

For a bare icon with transparent container, add slds-button_icon-container to the <button>. To add a border, use the slds-button_icon-border class instead.

For a neutral themed button icon, with border and a filled background, use the slds-button_icon-border-filled class to the slds-button class.

Use the inverse button on dark backgrounds by adding the slds-button_inverse class to the slds-button class.

Bare - transparent container
<div style="padding:0.5rem;background-color:#f4f6f9">
  <button class="slds-button slds-button_icon slds-button_icon-container" title="Search">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>
Bordered - filled container
<div style="padding:0.5rem;background-color:#f4f6f9">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" title="Search">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>
Bordered - transparent container
<div style="padding:0.5rem;background-color:#f4f6f9">
  <button class="slds-button slds-button_icon slds-button_icon-border" title="Search">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>
Bordered inverse - transparent container
<div style="padding:0.5rem;background-color:#16325C">
  <button class="slds-button slds-button_icon slds-button_icon-border-inverse" title="Search">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>

Stateful#

The stateful button requires the slds-button_icon-border class in addition to the slds-button class.The stateful inverse button works just like the stateful button. It requires the slds-button_icon-border-inverse class in addition to the slds-button class.

<button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-pressed="false" title="Like">
  <svg class="slds-button__icon" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#like"></use>
  </svg>

Accessibility Note

For accessibility, implement the ARIA Toggle Button concept.

  • Similar to a mute button, the button represents a pressed or unpressed state.
  • Button text doesn't change per state
  • aria-pressed is set to true or false, depending on its state

Selected#

Stateful icons can be toggled on and off and will retain their state. JavaScript is used to add the slds-is-selected class to the button when activated.

<button class="slds-button slds-button_icon slds-is-selected slds-button_icon-border-filled" aria-pressed="true" title="Like">
  <svg class="slds-button__icon" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#like"></use>
  </svg>

Disabled#

You can disable a stateful button icon by applying the disabled attribute to the .slds-button_icon. This will apply our disabled UI to the button icon, and freeze the button icon either in its selected or unselected state.

<button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-pressed="false" disabled="" title="Pin">
  <svg class="slds-button__icon" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#pin"></use>
  </svg>

Sizes#

Bare Icon#

The bare variant can be displayed in three other sizes—large, small, x-small—by adding a sizing class on the <svg> icon itself.

<button>
  <svg class="...slds-button__icon_{size}">...</svg>...</button>
<button class="slds-button slds-button_icon" title="More Options">
  <svg class="slds-button__icon slds-button__icon_large" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#settings"></use>
  </svg>

Icon Container#

Contained variants can be displayed in three smaller sizes—small, x-small, xx-small—by adding a sizing class on the <button>.

<button class="...slds-button_icon-{size}">...</button>
<button class="slds-button slds-button_icon slds-button_icon-border slds-button_icon-small" title="More Options">
  <svg class="slds-button__icon" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#settings"></use>
  </svg>

States#

Disabled#

Use a disabled attribute when a button can’t be clicked.

To create a disabled button, append the disabled attribute to the <button>.

<button class="slds-button slds-button_icon ..." disabled="">...</button>
Base
<button class="slds-button slds-button_icon" disabled="" title="Settings">
  <svg class="slds-button__icon" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#settings"></use>
  </svg>
Brand
<button class="slds-button slds-button_icon slds-button_icon-brand" title="Search" disabled="">
  <svg class="slds-button__icon" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>
  </svg>
Transparent container
<div style="padding:0.5rem;background-color:#f4f6f9">
  <button class="slds-button slds-button_icon slds-button_icon-container" title="Search" disabled="">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>
Inverse
<div style="padding:0.5rem;background-color:#16325C">
  <button class="slds-button slds-button_icon slds-button_icon-inverse" title="Search" disabled="">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>
Bordered filled container
<div style="padding:0.5rem;background-color:#f4f6f9">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" disabled="" title="Search">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>
Bordered transparent
<div style="padding:0.5rem;background-color:#f4f6f9">
  <button class="slds-button slds-button_icon slds-button_icon-border" title="Search" disabled="">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>
Bordered inverse
<div style="padding:0.5rem;background-color:#16325C">
  <button class="slds-button slds-button_icon slds-button_icon-border-inverse" disabled="" title="Search">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#search"></use>

Error#

Error button icons are typically used in conjunction with an error popover.

<button class="slds-button slds-button_icon slds-button_icon-error" title="Error">
  <svg class="slds-button__icon" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#error"></use>
  </svg>

Examples#

Hint on hover#

A parent class, slds-hint-parent, must be put on any wrapper, and slds-button__icon_hint must be added to the button's <svg> so that the child reacts when the parent is hovered.

<div class="slds-hint-parent">
  <button class="slds-button slds-button_icon">
    <svg class="slds-button__icon slds-button__icon_hint">...</svg>...</button>
</div>
Base
<div class="slds-hint-parent">
  <button class="slds-button slds-button_icon" title="Settings">
    <svg class="slds-button__icon slds-button__icon_hint" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#settings"></use>
Transparent container
<div style="padding:0.5rem;background-color:#f4f6f9">
  <div class="slds-hint-parent">
    <button class="slds-button slds-button_icon slds-button_icon-container" title="More Options">
      <svg class="slds-button__icon slds-button__icon_hint" aria-hidden="true">
Bordered filled container
<div style="padding:0.5rem;background-color:#f4f6f9">
  <div class="slds-hint-parent">
    <button class="slds-button slds-button_icon slds-button_icon-border-filled" title="More Options">
      <svg class="slds-button__icon slds-button__icon_hint" aria-hidden="true">
Bordered transparent
<div style="padding:0.5rem;background-color:#f4f6f9">
  <div class="slds-hint-parent">
    <button class="slds-button slds-button_icon slds-button_icon-border" title="More Options">
      <svg class="slds-button__icon slds-button__icon_hint" aria-hidden="true">

Inverse#

In the case of inverse, use the slds-button__icon_inverse-hint class on the button's <svg> instead.

<div class="slds-hint-parent">
  <button class="slds-button slds-button_icon">
    <svg class="slds-button__icon slds-button__icon_inverse-hint">...</svg>...</button>
</div>
Inverse
<div style="padding:0.5rem;background-color:#16325C">
  <div class="slds-hint-parent">
    <button class="slds-button slds-button_icon slds-button_icon-inverse" title="More Options">
      <svg class="slds-button__icon slds-button__icon_inverse-hint" aria-hidden="true">
Bordered inverse
<div style="padding:0.5rem;background-color:#16325C">
  <div class="slds-hint-parent">
    <button class="slds-button slds-button_icon slds-button_icon-border-inverse" title="More Options">
      <svg class="slds-button__icon slds-button__icon_inverse-hint" aria-hidden="true">

With a Dropdown#

If the button opens a menu, add slds-button_icon-more class to the <button> and a down icon within the button to indicate the behavior.

<button class="slds-button slds-button_icon slds-button_icon-container-more">...
  <svg class="slds-button__icon slds-button__icon_x-small">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>
  </svg>...</button>
Transparent container
<div style="padding:0.5rem;background-color:#f4f6f9">
  <button class="slds-button slds-button_icon slds-button_icon-container-more" aria-haspopup="true" title="More Options">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#settings"></use>
Inverse
<div style="padding:0.5rem;background-color:#16325C">
  <button class="slds-button slds-button_icon slds-button_icon-container-more slds-button_icon-inverse" aria-haspopup="true" title="More Options">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#settings"></use>
Bordered filled container
<div style="padding:0.5rem;background-color:#f4f6f9">
  <button class="slds-button slds-button_icon slds-button_icon-more" aria-haspopup="true" title="More Options">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#settings"></use>
Bordered inverse
<div style="padding:0.5rem;background-color:#16325C">
  <button class="slds-button slds-button_icon slds-button_icon-more" aria-haspopup="true" title="More Options">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#settings"></use>

Overview of CSS Classes#

Selector.slds-button_icon
Summary

Creates a button that looks like a plain icon

Supportdev-ready
Restrictbutton
VariantTrue
Selector.slds-button_icon-container
Summary

Default width + height for button icon with containers

Restrict.slds-button_icon
Selector.slds-button_icon-border
Summary

Transparent themed button icon - Button icon has a border with a transparent background

Restrict.slds-button_icon
Selector.slds-button_icon-border-inverse
Summary

Button icon with border and transparent background, to be used on an inversed background

Restrict.slds-button_icon
Selector.slds-button_icon-brand
Summary

Branded button icon - Button icon has a filled background with the brand color

Restrict.slds-button_icon
Selector.slds-button_icon-border-filled
Summary

Neutral themed button icon - Button icon has a border with a filled background

Restrict.slds-button_icon
Selector.slds-button_icon-inverse
Summary

Bare button icon with no border or background, to be used on an inversed background

Restrict.slds-button_icon
Selector.slds-button_icon-error
Summary

Error state - Typically used in conjunction with an error toolip

Restrict.slds-button_icon
Selector.slds-button_icon-current-color
Summary

Apply the current color to the icon contained within

Restrict.slds-button_icon
Selector.slds-button_icon-small
Summary

Changes a button icon container to be 24x24px

Restrict.slds-button_icon
Selector.slds-button_icon-x-small
Summary

Changes a button icon container to be 20x20px

Restrict.slds-button_icon
Selector.slds-button_icon-xx-small
Summary

Changes a button icon container to be 16x16px

Restrict.slds-button_icon
Selector.slds-button_icon-more
Summary

Creates a button menu icon container that has borders and a filled background

Restrict.slds-button_icon
Selector.slds-button_icon-container-more
Summary

Creates a button menu icon container that has no borders

Restrict.slds-button_icon
Selector.slds-button__icon_hint
Summary

A parent class must be put on anything that contains a .slds-button__icon_hint so that the child reacts when the parent is hovered.

Restrict.slds-button_icon .slds-button__icon
Selector.slds-button__icon_inverse-hint
Summary

A parent class must be put on anything that contains a .slds-button__icon_inverse-hint so that the child reacts when the parent is hovered. This is for a dark background.

Restrict.slds-button_icon .slds-button__icon
Selector.slds-is-selected
Summary

Stateful Button Icon

Supportdev-ready
Restrict.slds-button_icon
VariantTrue
Selector.slds-button_icon-border-filled
Summary

Creates a button icon inside of a filled container with a border

Supportdev-ready
Restrictbutton
VariantTrue
Selector.slds-button_icon-border-inverse
Summary

Creates a button icon inside of a transparent container with a border on an inversed background

Supportdev-ready
Restrictbutton
VariantTrue
Selector.slds-button_icon-border
Summary

Creates a button icon inside of a transparent container with a border

Supportdev-ready
Restrictbutton
VariantTrue
Selector.slds-button_icon-brand
Summary

Creates a brand button icon

Supportdev-ready
Restrictbutton
VariantTrue
Selector.slds-button_icon-inverse
Summary

Creates a button icon inside of a transparent container with a border on an inversed background

Supportdev-ready
Restrictbutton
VariantTrue
Selector.slds-button_icon-container
Summary

Creates a button icon inside of a transparent container

Supportdev-ready
Restrictbutton
VariantTrue

Button Icons Release Notes

2.11.6

Fixed

  • Sizing classes are now respected in mobile/touch context

Added

  • Added documentation and examples for mobile/touch context

2.10.0

Changed

  • Center contents of slds-button_icon with change of display: inline-flex to slds-button

2.8.0

Added

  • Added support for disabled stateful button icons

2.7.0

Added

  • Added a title and assistive text to most button icon examples