lion/packages/icon/README.md

Icon

A web component for displaying icons.

import { html } from 'lit-html';
import { icons } from './index.js';
import './docs/icons/iconset-bugs.js';
import './docs/icons/iconset-misc.js';
import * as spaceSet from './docs/icons/iconset-space.js';

import './lion-icon.js';

export default {
  title: 'Icons/Icon',
};

icons.addIconResolver('lion', (iconset, name) => {
  switch (iconset) {
    case 'bugs':
      return import('./docs/icons/iconset-bugs.js').then(module => module[name]);
    case 'space':
      return import('./docs/icons/iconset-space.js').then(module => module[name]);
    case 'misc':
      return import('./docs/icons/iconset-misc.js').then(module => module[name]);
    default:
      throw new Error(`Unknown iconset ${iconset}`);
  }
});

export const main = () => html`
  <lion-icon icon-id="lion:space:alienSpaceship" style="width: 50px; height: 50px;"></lion-icon>
`;

Live Demo/Documentation

See our storybook for a live demo and documentation

How to use

Installation

npm i --save @lion/icon

import { LionIcon } from '@lion/icon';
// or
import '@lion/icon/lion-icon.js';

Icon sets

Icons are displayed using icon sets. These are collections of icons, lazily loaded on demand for performance. See the system documentation to learn more about icon sets.

export const iconSets = () => html`
  ${Object.keys(spaceSet).map(
    name => html`
      <style>
        .demo-icon__container {
          display: inline-flex;
          position: relative;
          flex-grow: 1;
          flex-direction: column;
          align-items: center;
          width: 80px;
          height: 80px;
          padding: 4px;
        }
        .demo-icon__name {
          font-size: 10px;
        }
      </style>
      <div class="demo-icon__container" title="lion:space:${name}">
        <lion-icon icon-id="lion:space:${name}" aria-label="icon: ${name}"></lion-icon>
        <span class="demo-icon__name">${name}</span>
      </div>
    `,
  )}
`;

If for some reason you don't want to lazy load icons, you can still import and use them synchronously.

Accessibility

It is recommended to add an aria-label to provide information to visually impaired users:

A lion-icon without an aria-label attribute will be automatically given an aria-hidden attribute.

export const accessibleLabel = () => html`
  <lion-icon icon-id="lion:misc:arrowLeft" aria-label="Pointing left"></lion-icon>
`;

Styling

By default, a lion-icon will be 1em × 1em (the current line-height).

lion-icon uses SVGs and may be styled with CSS, including using CSS properties such as fill:

export const Styling = () => html`
  <style>
    .demo-icon {
      width: 160px;
      height: 160px;
      fill: blue;
    }
  </style>
  <lion-icon icon-id="lion:bugs:bug02" aria-label="Bug" class="demo-icon"></lion-icon>
`;

See SVG and CSS on MDN web docs for more information.