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

For a full list of icons that come bundled with Shoelace, refer to the icon component. 

<sl-icon-button name="cog-6-tooth" label="Settings"></sl-icon-button>

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

Sizes

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

<sl-icon-button name="pencil" label="Edit" style="font-size: 1.5rem;"></sl-icon-button>
<sl-icon-button name="pencil" label="Edit" style="font-size: 2rem;"></sl-icon-button>
<sl-icon-button name="pencil" label="Edit" style="font-size: 2.5rem;"></sl-icon-button>

sl-icon-button name="pencil" label="Edit" style="font-size: 1.5rem;"
sl-icon-button name="pencil" label="Edit" style="font-size: 2rem;"
sl-icon-button name="pencil" label="Edit" style="font-size: 2.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 name="at-symbol" label="Bold"></sl-icon-button>
  <sl-icon-button name="bolt" label="Italic"></sl-icon-button>
  <sl-icon-button name="no-symbol" label="Underline"></sl-icon-button>
</div>

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

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

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

div.icon-button-color
  sl-icon-button name="at-symbol" label="Bold"
  sl-icon-button name="bolt" label="Italic"
  sl-icon-button name="no-symbol" label="Underline"

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

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

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

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

<sl-icon-button name="cog-6-tooth" label="Settings" href="https://example.com" target="_blank"></sl-icon-button>

sl-icon-button name="cog-6-tooth" label="Settings" 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="Settings">
  <sl-icon-button name="cog-6-tooth" label="Settings"></sl-icon-button>
</sl-tooltip>

sl-tooltip content="Settings"
  sl-icon-button name="cog-6-tooth" label="Settings"

Disabled

Use the disabled attribute to disable the icon button.

<sl-icon-button name="cog-6-tooth" 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>