button-icons

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.

Select a device to set the width of the example

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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>

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

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

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

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

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>

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

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

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>

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

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

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

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