Light Dark System
Get ready for more awesome! Web Awesome, the next iteration of Shoelace, is on Kickstarter. Read Our Story

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>

import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';

const App = () => <SlIconButton name="gear" label="Settings" />;

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>

import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';

const App = () => (
  <>
    <SlIconButton name="pencil" label="Edit" style={{ fontSize: '1.5rem' }} />
    <SlIconButton name="pencil" label="Edit" style={{ fontSize: '2rem' }} />
    <SlIconButton name="pencil" label="Edit" style={{ fontSize: '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="type-bold" label="Bold"></sl-icon-button>
  <sl-icon-button name="type-italic" label="Italic"></sl-icon-button>
  <sl-icon-button name="type-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>

import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';

const 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;
  }
`;

const App = () => (
  <>
    <div className="icon-button-color">
      <SlIconButton name="type-bold" label="Bold" />
      <SlIconButton name="type-italic" label="Italic" />
      <SlIconButton name="type-underline" label="Underline" />
    </div>

    <style>{css}</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>

import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';

const App = () => <SlIconButton name="gear" 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="gear" label="Settings"></sl-icon-button>
</sl-tooltip>

import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';
import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';

const App = () => (
  <SlTooltip content="Settings">
    <SlIconButton name="gear" label="Settings" />
  </SlTooltip>
);

Disabled

Use the disabled attribute to disable the icon button.

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

import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';

const App = () => <SlIconButton name="gear" label="Settings" disabled />;

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.16.0/cdn/components/icon-button/icon-button.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.16.0/cdn/components/icon-button/icon-button.js';

To import this component using a bundler:

import '@shoelace-style/shoelace/dist/components/icon-button/icon-button.js';

To import this component as a React component:

import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';

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
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 onSlBlur Emitted when the icon button loses focus. -
sl-focus onSlFocus 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>