Button Icons
- HTML/CSS:Dev Ready
- Web Component:In Progress (1 of 8 variants)
- Layout:Responsive
Sections
You are currently viewing a sandbox preview version of Spring ’20 | Go back to Summer ’20
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.
<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>
<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>
<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>
<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 totrue
orfalse
, 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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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">
<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">
<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>
<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">
<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>
<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>
<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>
<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>
<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
- 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-button_icon |
---|---|
Summary | Creates a button that looks like a plain icon |
Support | dev-ready |
Restrict | button |
Variant | True |
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 |
Support | dev-ready |
Restrict | .slds-button_icon |
Variant | True |
Selector | .slds-button_icon-border-filled |
---|---|
Summary | Creates a button icon inside of a filled container with a border |
Support | dev-ready |
Restrict | button |
Variant | True |
Selector | .slds-button_icon-border-inverse |
---|---|
Summary | Creates a button icon inside of a transparent container with a border on an inversed background |
Support | dev-ready |
Restrict | button |
Variant | True |
Selector | .slds-button_icon-border |
---|---|
Summary | Creates a button icon inside of a transparent container with a border |
Support | dev-ready |
Restrict | button |
Variant | True |
Selector | .slds-button_icon-brand |
---|---|
Summary | Creates a brand button icon |
Support | dev-ready |
Restrict | button |
Variant | True |
Selector | .slds-button_icon-inverse |
---|---|
Summary | Creates a button icon inside of a transparent container with a border on an inversed background |
Support | dev-ready |
Restrict | button |
Variant | True |
Selector | .slds-button_icon-container |
---|---|
Summary | Creates a button icon inside of a transparent container |
Support | dev-ready |
Restrict | button |
Variant | True |
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 ofdisplay: inline-flex
toslds-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