Icon

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

Default Icons

Iconify is yoummdays default source of icons, therefore the following is all possible. Also, there are some custom icons as additional libraries located in ./src/components/icon/custom-icons directory.

<h2>
  <!-- aware of surrounding font-size -->
  <sl-icon name="mdi:information"></sl-icon>
  <sl-icon name="cif:de"></sl-icon>
  <sl-icon name="fxemoji:blowfish"></sl-icon>
  <sl-icon name="trash" library="shoelace-default"></sl-icon>
</h2>
<h2>
  <!-- width set explicitely -->
  <sl-icon name="world" library="undraw" width="200"></sl-icon>
</h2>
<h2>
  <!-- width set explicitely -->
  <sl-icon name="logo" library="ymmd" width="200"></sl-icon>
</h2>

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="mdi:information"></sl-icon>
  <sl-icon name="mdi:check"></sl-icon>
  <sl-icon name="mdi:help"></sl-icon>
  <sl-icon name="mdi:external-link"></sl-icon>
</div>
<div style="color: #9013fe;">
  <sl-icon name="mdi:information"></sl-icon>
  <sl-icon name="mdi:check"></sl-icon>
  <sl-icon name="mdi:help"></sl-icon>
  <sl-icon name="mdi:external-link"></sl-icon>
</div>
<div style="color: #417505;">
  <sl-icon name="mdi:information"></sl-icon>
  <sl-icon name="mdi:check"></sl-icon>
  <sl-icon name="mdi:help"></sl-icon>
  <sl-icon name="mdi:external-link"></sl-icon>
</div>

import SlIcon from '@yoummday/ymmd-shoelace/dist/react/icon';

const App = () => (
  <>
    <div style={{ color: '#4a90e2' }}>
      <SlIcon name="exclamation-triangle" library="shoelace-default"></SlIcon>
      <SlIcon name="archive" library="shoelace-default"></SlIcon>
      <SlIcon name="battery-charging" library="shoelace-default"></SlIcon>
      <SlIcon name="bell" library="shoelace-default"></SlIcon>
    </div>
    <div style={{ color: '#9013fe' }}>
      <SlIcon name="clock" library="shoelace-default"></SlIcon>
      <SlIcon name="cloud" library="shoelace-default"></SlIcon>
      <SlIcon name="download" library="shoelace-default"></SlIcon>
      <SlIcon name="file-earmark" library="shoelace-default"></SlIcon>
    </div>
    <div style={{ color: '#417505' }}>
      <SlIcon name="flag" library="shoelace-default"></SlIcon>
      <SlIcon name="heart" library="shoelace-default"></SlIcon>
      <SlIcon name="image" library="shoelace-default"></SlIcon>
      <SlIcon name="lightning" library="shoelace-default"></SlIcon>
    </div>
    <div style={{ color: '#f5a623' }}>
      <SlIcon name="mic" library="shoelace-default"></SlIcon>
      <SlIcon name="search" library="shoelace-default"></SlIcon>
      <SlIcon name="star" library="shoelace-default"></SlIcon>
      <SlIcon name="trash" library="shoelace-default"></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="mdi:information"></sl-icon>
  <sl-icon name="mdi:check"></sl-icon>
  <sl-icon name="mdi:help"></sl-icon>
  <sl-icon name="mdi:external-link"></sl-icon>
</div>

import SlIcon from '@yoummday/ymmd-shoelace/dist/react/icon';

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

Labels

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

<sl-icon name="mdi:external-link" label="Open in new window"></sl-icon>

import SlIcon from '@yoummday/ymmd-shoelace/dist/react/icon';

const App = () => <SlIcon name="star-fill" 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, it might make sense to register a custom icon library.

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

import SlIcon from '@yoummday/ymmd-shoelace/dist/react/icon';

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

Icon Libraries

You can register additional icons to use with the <sl-icon> component through icon libraries. Icon files can exist locally or on a CORS-enabled endpoint (e.g. a CDN). There is no limit to how many icon libraries you can register and there is no cost associated with registering them, as individual icons are only requested when they’re used.

Shoelace ships with two built-in icon libraries, default and system. The default icon library contains all of the icons in the Bootstrap Icons project. The system icon library contains only a small subset of icons that are used internally by Shoelace components.

To register an additional icon library, use the registerIconLibrary() function that’s exported from utilities/icon-library.js. At a minimum, you must provide a name and a resolver function. The resolver function translates an icon name to a URL where the corresponding SVG file exists. Refer to the examples below to better understand how it works.

If necessary, a mutator function can be used to mutate the SVG element before rendering. This is necessary for some libraries due to the many possible ways SVGs are crafted. For example, icons should ideally inherit the current text color via currentColor, so you may need to apply fill="currentColor or stroke="currentColor" to the SVG element using this function.

Here’s an example that registers an icon library located in the /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, set the library and name attributes of an <sl-icon> element.

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

If an icon is used before registration occurs, it will be empty initially but shown when registered.

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 type="module" src="https://v2-58-0.yoummday-theme.pages.dev/components/icon/icon.js"></script>

import 'https://v2-58-0.yoummday-theme.pages.dev/components/icon/icon.js';

import '@yoummday/ymmd-shoelace/dist/components/icon/icon.js';

import SlIcon from '@yoummday/ymmd-shoelace/dist/react/icon';

Properties

Learn more about attributes and properties.

Events

Learn more about events.

Parts

Learn more about customizing CSS parts.