Icon

<sl-icon> | SlIcon
Since 2.0 stable

Icons are symbols that can be used to represent various options within an application.

The design system ships with over 1,500 icons from the Lucide project. These icons are part of the default icon library. If you need more, you can register your own icons individually or as a custom icon library.

Default Icons

All available icons in the default icon library are shown below. Click or tap on any icon to copy its name, then you can use it in your HTML like this. 

<sl-icon name="icon-name-here"></sl-icon>

Examples

Colors

Icons inherit their color from the current text color. Thus, you can set the color property on the <sl-icon> element or an ancestor to change the color. 

<div style="color: #4a90e2;">
  <sl-icon name="triangle-alert"></sl-icon>
  <sl-icon name="archive"></sl-icon>
  <sl-icon name="battery-charging"></sl-icon>
  <sl-icon name="bell"></sl-icon>
</div>
<div style="color: #9013fe;">
  <sl-icon name="clock"></sl-icon>
  <sl-icon name="cloud"></sl-icon>
  <sl-icon name="download"></sl-icon>
  <sl-icon name="file"></sl-icon>
</div>
<div style="color: #417505;">
  <sl-icon name="flag"></sl-icon>
  <sl-icon name="heart"></sl-icon>
  <sl-icon name="image"></sl-icon>
  <sl-icon name="zap"></sl-icon>
</div>
<div style="color: #f5a623;">
  <sl-icon name="mic"></sl-icon>
  <sl-icon name="search"></sl-icon>
  <sl-icon name="star"></sl-icon>
  <sl-icon name="trash"></sl-icon>
</div>

import SlIcon from '@decked/decked-design-system/dist/react/icon';

const App = () => (
  <>
    <div style={{ color: '#4a90e2' }}>
      <SlIcon name="triangle-alert"></SlIcon>
      <SlIcon name="archive"></SlIcon>
      <SlIcon name="battery-charging"></SlIcon>
      <SlIcon name="bell"></SlIcon>
    </div>
    <div style={{ color: '#9013fe' }}>
      <SlIcon name="clock"></SlIcon>
      <SlIcon name="cloud"></SlIcon>
      <SlIcon name="download"></SlIcon>
      <SlIcon name="file"></SlIcon>
    </div>
    <div style={{ color: '#417505' }}>
      <SlIcon name="flag"></SlIcon>
      <SlIcon name="heart"></SlIcon>
      <SlIcon name="image"></SlIcon>
      <SlIcon name="zap"></SlIcon>
    </div>
    <div style={{ color: '#f5a623' }}>
      <SlIcon name="mic"></SlIcon>
      <SlIcon name="search"></SlIcon>
      <SlIcon name="star"></SlIcon>
      <SlIcon name="trash"></SlIcon>
    </div>
  </>
);

Sizing

Icons are sized relative to the current font size. To change their size, set the font-size property on the icon itself or on a parent element as shown below. 

<div style="font-size: 32px;">
  <sl-icon name="triangle-alert"></sl-icon>
  <sl-icon name="archive"></sl-icon>
  <sl-icon name="battery-charging"></sl-icon>
  <sl-icon name="bell"></sl-icon>
  <sl-icon name="clock"></sl-icon>
  <sl-icon name="cloud"></sl-icon>
  <sl-icon name="download"></sl-icon>
  <sl-icon name="file"></sl-icon>
  <sl-icon name="flag"></sl-icon>
  <sl-icon name="heart"></sl-icon>
  <sl-icon name="image"></sl-icon>
  <sl-icon name="zap"></sl-icon>
  <sl-icon name="mic"></sl-icon>
  <sl-icon name="search"></sl-icon>
  <sl-icon name="star"></sl-icon>
  <sl-icon name="trash"></sl-icon>
</div>

import SlIcon from '@decked/decked-design-system/dist/react/icon';

const App = () => (
  <div style={{ fontSize: '32px' }}>
    <SlIcon name="triangle-alert" />
    <SlIcon name="archive" />
    <SlIcon name="battery-charging" />
    <SlIcon name="bell" />
    <SlIcon name="clock" />
    <SlIcon name="cloud" />
    <SlIcon name="download" />
    <SlIcon name="file" />
    <SlIcon name="flag" />
    <SlIcon name="heart" />
    <SlIcon name="image" />
    <SlIcon name="zap" />
    <SlIcon name="mic" />
    <SlIcon name="search" />
    <SlIcon name="star" />
    <SlIcon name="trash" />
  </div>
);

Labels

For non-decorative icons, use the label attribute to announce it to assistive devices.

<sl-icon name="star" label="Add to favorites"></sl-icon>

import SlIcon from '@decked/decked-design-system/dist/react/icon';

const App = () => <SlIcon name="star" label="Add to favorites" />;

Custom Icons

Custom icons can be loaded individually with the src attribute. Only SVGs on a local or CORS-enabled endpoint are supported. If you’re using more than one custom icon, register a custom icon library instead. 

<sl-icon src="/assets/images/shoe.svg" style="font-size: 8rem;"></sl-icon>

import SlIcon from '@decked/decked-design-system/dist/react/icon';

const App = () => <SlIcon src="/assets/images/shoe.svg" style={{ fontSize: '8rem' }}></SlIcon>;

Icon Libraries

If you have a set of custom icons you want to use throughout your app, register them as an icon library. Icon files can be local or on a CORS-enabled endpoint. There is no limit to how many icon libraries you can register, and there is no cost to registering them — individual icons are only fetched when used.

Two libraries are built in:

  • default — the Lucide icon set, served from your local assets directory.
  • system — a small set of icons used internally by components. These are inlined as data URIs to guarantee availability.

To register an additional library, use registerIconLibrary() from utilities/icon-library.js. At minimum, provide a name and a resolver function that maps an icon name to a URL.

If needed, a mutator function can modify the SVG element before rendering — useful for ensuring fill="currentColor" or stroke="currentColor" so icons inherit text color.

Here’s an example registering an icon library located in your /assets/icons directory:

<script type="module">
  import { registerIconLibrary } from '/dist/utilities/icon-library.js';

  registerIconLibrary('my-icons', {
    resolver: name => `/assets/icons/${name}.svg`,
    mutator: svg => svg.setAttribute('fill', 'currentColor')
  });
</script>

To display an icon from your library, set the library and name attributes on <sl-icon>: 

<!-- This will show the icon located at /assets/icons/smile.svg -->
<sl-icon library="my-icons" name="smile"></sl-icon>

If an icon is referenced before its library is registered, it will be empty initially and shown when registration occurs.

Customizing the Default Library

The default library is what <sl-icon> resolves when you don’t specify a library attribute. If you want to swap it for your own set of icons, register a library named default: 

<script type="module">
  import { registerIconLibrary } from '/dist/utilities/icon-library.js';

  registerIconLibrary('default', {
    resolver: name => `/path/to/your/icons/${name}.svg`,
    mutator: svg => svg.setAttribute('fill', 'currentColor')
  });
</script>

Using SVG Sprites

To reduce the number of network requests, you can serve an SVG sprite sheet and reference individual icons via hash selectors. The browser loads the sprite once and reuses it.

Benchmark before adopting — over HTTP/2, many small requests can be more bandwidth-friendly than one large sprite. 

<script type="module">
  import { registerIconLibrary } from '/dist/utilities/icon-library.js';

  registerIconLibrary('sprite', {
    resolver: name => `/assets/images/sprite.svg#${name}`,
    mutator: svg => svg.setAttribute('fill', 'currentColor'),
    spriteSheet: true
  });
</script>

<div style="font-size: 24px;">
  <sl-icon library="sprite" name="clock"></sl-icon>
  <sl-icon library="sprite" name="zap"></sl-icon>
</div>

Customizing the System Library

The system library contains the icons used internally by components. Unlike the default library, its icons are inlined as data URIs and don’t depend on any physical assets.

If you want to replace these icons, register a library named system and provide all the icons components rely on. See src/components/icon/library.system.ts for the complete list. 

<script type="module">
  import { registerIconLibrary } from '/dist/utilities/icon-library.js';

  registerIconLibrary('system', {
    resolver: name => `/path/to/custom/icons/${name}.svg`
  });
</script>

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/@decked/decked-design-system@0.0.6/cdn/components/icon/icon.js"></script>

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

import 'https://cdn.jsdelivr.net/npm/@decked/decked-design-system@0.0.6/cdn/components/icon/icon.js';

To import this component using a bundler:

import '@decked/decked-design-system/dist/components/icon/icon.js';

To import this component as a React component:

import SlIcon from '@decked/decked-design-system/dist/react/icon';

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 -
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 -
label An alternate description to use for assistive devices. If omitted, the icon will be considered presentational and ignored by assistive devices. string ''
library The name of a registered custom icon library. string 'default'
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-load onSlLoad Emitted when the icon has loaded. When using spriteSheet: true this will not emit. -
sl-error onSlError Emitted when the icon fails to load due to an error. When using spriteSheet: true this will not emit. -

Learn more about events.

Parts

Name Description
svg The internal SVG element.
use The element generated when using spriteSheet: true

Learn more about customizing CSS parts.