Icon Button

<sl-icon-button> | SlIconButton
Since 2.0 stable

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

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

<sl-icon-button name="gear" label="Settings"></sl-icon-button>

Examples

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>

Padding

By default, icons get padding to make them easier to click. To change, use the –sl-icon-button-spacing token 

<sl-icon-button name="gear" label="Settings" style="--sl-icon-button-spacing: 0px"></sl-icon-button>

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="bold" label="Bold"></sl-icon-button>
  <sl-icon-button name="italic" label="Italic"></sl-icon-button>
  <sl-icon-button name="underline" 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>

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

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

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="gear" label="Settings"></sl-icon-button>
</sl-tooltip>

Disabled

Use the disabled attribute to disable the icon button.

<sl-icon-button name="gear" label="Settings" disabled></sl-icon-button>

Light mode

Use the light attribute when placing an icon button on a light background

<div style="background-color: yellow; padding: 10px; font-size: 24px;">
  <sl-icon-button name="gear" label="Settings" light></sl-icon-button>
</div>

Dark mode

Use the dark attribute when placing an icon button on a dark background

<div style="background-color: darkblue; padding: 10px; font-size: 24px;">
  <sl-icon-button name="gear" label="Settings" dark></sl-icon-button>
</div>

Properties

Name Description Reflects Type Default
name The name of the icon to draw. Available names depend on the icon library being used. string | undefined -
library The name of a registered custom icon library. string | undefined -
src 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. string | undefined -
href When set, the underlying button will be rendered as an <a> with this href instead of a <button>. string | undefined -
target Tells the browser where to open the link. Only used when href is set. '_blank' | '_parent' | '_self' | '_top' | undefined -
download Tells the browser to download the linked file as this filename. Only used when href is set. string | undefined -
label A description that gets read by assistive devices. For optimal accessibility, you should always include a label that describes what the icon button does. string ''
disabled Disables the button. boolean false
dark Dark mode boolean false
light Light mode boolean false
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
sl-blur Emitted when the icon button loses focus. -
sl-focus Emitted when the icon button gains focus. -

Learn more about events.

Methods

Name Description Arguments
click() Simulates a click on the icon button. -
focus() Sets focus on the icon button. options: FocusOptions
blur() Removes focus from the icon button. -

Learn more about methods.

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>