Since Shoelace 2.0 Code stable Pattern stable Figma ready

Icon Button

sl-icon-button

Icons buttons are simple, icon-only buttons that can be used for actions and in toolbars.

Examples

Basic Icon Button

Our official Design System icon set is Font Awesome. Use Font Awesome icons when displaying Icon Buttons by setting the sl-icon-button’s library attribute to fa and passing the icon’s name to the name attribute.

This will display Regular style icons by default:

<sl-icon-button library="fa" name="cog" label="Settings"></sl-icon-button>

sl-icon-button library="fa" name="cog" label="Settings"

Sizes

Icon buttons inherit their parent element’s font-size.

<sl-icon-button library="fa" name="pencil" label="Edit" style="font-size: 1rem;"></sl-icon-button>
<sl-icon-button library="fa" name="pencil" label="Edit" style="font-size: 1.25rem;"></sl-icon-button>
<sl-icon-button library="fa" name="pencil" label="Edit" style="font-size: 1.5rem;"></sl-icon-button>

sl-icon-button library="fa" name="pencil" label="Edit" style="font-size: 1rem;"
sl-icon-button library="fa" name="pencil" label="Edit" style="font-size: 1.25rem;"
sl-icon-button library="fa" name="pencil" label="Edit" style="font-size: 1.5rem;"

Colors

Icon buttons are designed to have a uniform appearance, so their color is not inherited. However, you can still customize them by styling the base part. 

<div class="icon-button-color">
  <sl-icon-button library="fa" name="envelope" label="Send email"></sl-icon-button>
  <sl-icon-button library="fa" name="building" label="Company"></sl-icon-button>
  <sl-icon-button library="fa" name="user-plus" label="Add employee"></sl-icon-button>
</div>

<style>
  .icon-button-color sl-icon-button::part(base) {
    color: #6339ac;
  }

  .icon-button-color sl-icon-button::part(base):hover,
  .icon-button-color sl-icon-button::part(base):focus {
    color: #6339ac;
  }

  .icon-button-color sl-icon-button::part(base):active {
    color: #6339ac;
  }
</style>

div.icon-button-color
  sl-icon-button library="fa" name="envelope" label="Send email"
  sl-icon-button library="fa" name="building" label="Company"
  sl-icon-button library="fa" name="user-plus" label="Add employee"

css:
  .icon-button-color sl-icon-button::part(base) {
    color: #6339ac;
  }

  .icon-button-color sl-icon-button::part(base):hover,
  .icon-button-color sl-icon-button::part(base):focus {
    color: #6339ac;
  }

  .icon-button-color sl-icon-button::part(base):active {
    color: #6339ac;
  }

Use the href attribute to convert the button to a link.

<sl-icon-button library="fa" name="arrow-up-right-from-square" label="Open link" href="https://example.com" target="_blank"></sl-icon-button>

sl-icon-button library="fa" name="arrow-up-right-from-square" label="Open link" href="https://example.com" target="_blank"

Icon Button with Tooltip

Wrap a tooltip around an icon button to provide contextual information to the user.

<sl-tooltip content="Update settings">
  <sl-icon-button library="fa" name="cog" label="Settings"></sl-icon-button>
</sl-tooltip>

sl-tooltip content="Update settings"
  sl-icon-button library="fa" name="cog" label="Settings"

Disabled

Use the disabled attribute to disable the icon button.

<sl-icon-button library="fa" name="cog" label="Settings" disabled></sl-icon-button>

sl-icon-button name="cog-6-tooth" label="Settings" disabled=true

Component Props

Property Default Details
name —

string | undefined

The name of the icon to draw. Available names depend on the icon library being used.
library —

string | undefined

The name of a registered custom icon library.
src —

string | undefined

An external URL of an SVG file. Be sure you trust the content you are including, as it will be executed as code and can result in XSS attacks.

href —

string | undefined

When set, the underlying button will be rendered as an <a> with this href instead of a <button>.

target —

'_blank' | '_parent' | '_self' | '_top' | undefined

Tells the browser where to open the link. Only used when href is set.
download —

string | undefined

Tells the browser to download the linked file as this filename. Only used when href is set.

label ''

string

A description that gets read by assistive devices. For optimal accessibility, you should always include a label that describes what the icon button does.

disabled false

boolean

Disables the button.
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name Name Name React Event Details
sl-blur sl-blur sl-blur onSlBlur

Emitted when the icon button loses focus.
sl-focus sl-focus sl-focus onSlFocus

Emitted when the icon button gains focus.

Learn more about events.

Methods

Name Details
click()

Simulates a click on the icon button.
focus()

options: FocusOptions

Sets focus on the icon button.
blur()

Removes focus from the icon button.

Learn more about methods.

CSS Parts

Name Description
base The component’s base wrapper.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <sl-icon>