Icon

<quiet-icon>

stable

since 1.0

Icons provide a visual representation of an object, action, or idea.

Quiet includes thousands of beautifully designed SVG icons from the popular Tabler Icons library. In addition, it's flexible enough that you can replace or supplement the default icon set.

<div style="font-size: 1.5rem;">
  <quiet-icon name="pencil"></quiet-icon>
  <quiet-icon name="settings"></quiet-icon>
  <quiet-icon name="trash"></quiet-icon>  
</div>

A common pitfall of this component is not setting the library's path. It's easy to do and, if you're not using the CDN, some assets won't be able to load without it. If you're not seeing icons where they should be, this is probably why!

Examples Jump to heading

Built-in icons Jump to heading

Quiet includes the popular Tabler Icons icon library out of the box. Use the name attribute to specify which icon should be drawn.

<div style="font-size: 1.5rem;">
  <quiet-icon name="home"></quiet-icon>
  <quiet-icon name="bug"></quiet-icon>
  <quiet-icon name="bell"></quiet-icon>
  <quiet-icon name="microphone"></quiet-icon>
  <quiet-icon name="message"></quiet-icon>
</div>

For a list of all available icons, please refer to the Tabler Icons. Be careful to copy the name of the icon, e.g. arrow-up, and not the SVG code!

Setting the icon family Jump to heading

Some libraries have more than one family of icons to group them into different styles. To specify the icon family, use the family attribute. Tabler Icons, the default icon library, has two families to choose from: filled and outline (default).

<div style="font-size: 1.5rem;">
  <quiet-icon family="outline" name="ghost"></quiet-icon>
  <quiet-icon family="outline" name="star"></quiet-icon>
  <quiet-icon family="outline" name="balloon"></quiet-icon>
  <quiet-icon family="outline" name="heart"></quiet-icon>

  <br>

  <quiet-icon family="filled" name="ghost"></quiet-icon>
  <quiet-icon family="filled" name="star"></quiet-icon>
  <quiet-icon family="filled" name="balloon"></quiet-icon>
  <quiet-icon family="filled" name="heart"></quiet-icon>
</div>

Labeling icons Jump to heading

By default, icons are considered presentational elements. However, you can add the label attribute to any icon to make it available to assistive devices such as screen readers.

<div style="font-size: 1.5rem;">
  <quiet-icon label="Edit" name="pencil"></quiet-icon>
  <quiet-icon label="Settings" name="settings"></quiet-icon>
  <quiet-icon label="Delete" name="trash"></quiet-icon>  
</div>

Changing the size Jump to heading

Icons are sized relative to the current font size. This allows you to place them into many contexts without having to explicitly size them. To change the size, set the font-size property on the icon or an ancestor element.

<quiet-icon name="thumb-up" style="font-size: 1.5em;"></quiet-icon>
<quiet-icon name="thumb-up" style="font-size: 2em;"></quiet-icon>
<quiet-icon name="thumb-up" style="font-size: 2.5em;"></quiet-icon>

Changing the stroke Jump to heading

You can change the thickness of the default icon library's icons by setting the stroke-width property on the icon. For best results, use a value between 1px and 2px at 0.25px intervals. If icons look too thick or thin at various sizes, try adjusting their stroke width!

<div style="font-size: 1.5rem;">
  <quiet-icon name="cat" style="stroke-width: 1px;"></quiet-icon>
  <quiet-icon name="cat" style="stroke-width: 1.5px;"></quiet-icon>
  <quiet-icon name="cat" style="stroke-width: 2px;"></quiet-icon>
</div>

This will only work for SVGs designed to have customizable strokes.

Changing the color Jump to heading

Icons inherit the current text color. To change it, set the color property on the icon or an ancestor element.

<div style="font-size: 1.5rem;">
  <quiet-icon name="gift" style="color: royalblue;"></quiet-icon>
  <quiet-icon name="gift" style="color: deeppink;"></quiet-icon>
  <quiet-icon name="gift" style="color: forestgreen;"></quiet-icon>
</div>

Registering icon libraries Jump to heading

You can register additional icon libraries using the registerIconLibrary() function. The example below has detailed comments explaining each step of the registration process, and additional examples can be found later in this section.

<script type="module">
  import { registerIconLibrary } from '/dist/quiet.js';

  // This registers a new icon library called "my-icons"
  registerIconLibrary('my-icons', {
    //
    // The resolve function is required. It must be a callback that 
    // accepts two string arguments: the name of the icon and an 
    // optional icon family (e.g. solid, outline). These values are 
    // passed through from: <quiet-icon name="..." family="...">
    //
    // The resolver must return a URL of an SVG located at a 
    // CORS-enabled endpoint. You can also return SVG data URIs.
    //
    resolve: (name, family) => {
      return `https://example.com/path/to/icons/${family}/${name}.svg`
    },
    //
    // The mutate function is optional. It must be a callback that 
    // accepts one argument, an `SVGElement`, you can use to modify 
    // the icon before it gets rendered.
    //
    // The mutator is handy when you're pulling in SVGs from, for 
    // example, a  CDN and you need to adjust the fill, stroke, and 
    // other properties.
    //
    mutate: svg =>  {
      svg.setAttribute('fill', 'currentColor');
    }
  });
</script>

It's fine to add icons to the page before registering an icon library. They just won't be fetched or rendered until registration.

You can unregister icon libraries using the unregisterIconLibrary() function. However, this will cause existing icons that reference the library to disappear. Unregistering can be useful when you no longer need to display icons from a specific library.

import { unregisterIconLibrary } from '/dist/quiet.js';

unregisterIconLibrary('my-icons');

Changing the default icon library Jump to heading

To change the default icon library, override it by registering a new one called default. This will let you skip setting <quiet-icon library="..."> on every single icon. This is only recommended if you want to completely replace the default icon library.

import { registerIconLibrary } from '/dist/quiet.js';

registerIconLibrary('default', {
  // ...
});

Changing the system icon library Jump to heading

Quiet also has a system icon library that provides a small number of icons for internal use. These icons are served as base64-encoded data URIs, which allows them to load instantly and not require the library path to be set.

Changing the system library isn't recommended, but it is possible. To change the system icon library, override it by registering a new one called system.

import { registerIconLibrary } from '/dist/quiet.js';

registerIconLibrary('system', {
  // ...
});

If you choose to change the system library, you must reimplement all of the system icons found in src/utilities/icon-library.ts. Otherwise, icons will be absent from the components that use them.

Bootstrap icons Jump to heading

This examples demonstrates how to load the Bootstrap Icons library using the jsDelivr CDN. Available families include regular (default) and filled.

<script type="module">
  import { registerIconLibrary } from '/dist/quiet.js';

  registerIconLibrary('bootstrap', {
    resolve: (name, family) => {
      const suffix = family === 'filled' ? '-fill' : '';
      return `https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/icons/${name}${suffix}.svg`
    }
  });
</script>

<div style="font-size: 1.5em;">
  <quiet-icon library="bootstrap" name="house"></quiet-icon>
  <quiet-icon library="bootstrap" name="bug"></quiet-icon>
  <quiet-icon library="bootstrap" name="bell"></quiet-icon>
  <quiet-icon library="bootstrap" name="mic"></quiet-icon>
  <quiet-icon library="bootstrap" name="chat"></quiet-icon>

  <br>

  <quiet-icon library="bootstrap" family="filled" name="house"></quiet-icon>
  <quiet-icon library="bootstrap" family="filled" name="bug"></quiet-icon>
  <quiet-icon library="bootstrap" family="filled" name="bell"></quiet-icon>
  <quiet-icon library="bootstrap" family="filled" name="mic"></quiet-icon>
  <quiet-icon library="bootstrap" family="filled" name="chat"></quiet-icon>
</div>

Boxicons Jump to heading

This example demonstrates how to load the Boxicons library using the jsDelivr CDN. Available families include regular (default), solid, and logos.

<script type="module">
  import { registerIconLibrary } from '/dist/quiet.js';

  registerIconLibrary('boxicons', {
    resolve: (name, family = 'regular') => {
      const baseUrl = 'https://cdn.jsdelivr.net/npm/boxicons@2.1.4/svg/';

      switch (family) {
        case 'solid':
          return `${baseUrl}solid/bxs-${name}.svg`;
        case 'logos':
          return `${baseUrl}logos/bxl-${name}.svg`;
        default:
          return `${baseUrl}regular/bx-${name}.svg`;
      }
    },
    mutate: svg => svg.setAttribute('fill', 'currentColor')
  });
</script>

<div style="font-size: 1.5em;">
  <quiet-icon library="boxicons" name="home"></quiet-icon>
  <quiet-icon library="boxicons" name="bug"></quiet-icon>
  <quiet-icon library="boxicons" name="bell"></quiet-icon>
  <quiet-icon library="boxicons" name="microphone"></quiet-icon>
  <quiet-icon library="boxicons" name="chat"></quiet-icon>

  <br>

  <quiet-icon library="boxicons" family="solid" name="home"></quiet-icon>
  <quiet-icon library="boxicons" family="solid" name="bug"></quiet-icon>
  <quiet-icon library="boxicons" family="solid" name="bell"></quiet-icon>
  <quiet-icon library="boxicons" family="solid" name="microphone"></quiet-icon>
  <quiet-icon library="boxicons" family="solid" name="chat"></quiet-icon>
</div>

Jam icons Jump to heading

This example demonstrates how to load the Jam icons library using the jsDelivr CDN. Available families include outline (default) and filled.

<script type="module">
  import { registerIconLibrary } from '/dist/quiet.js';

  registerIconLibrary('jam', {
    resolve: (name, family) => {
      const suffix = family === 'filled' ? '-f' : '';
      return `https://cdn.jsdelivr.net/npm/jam-icons@2.0.0/svg/${name}${suffix}.svg`;
    },
    mutate: svg => svg.setAttribute('fill', 'currentColor')
  });
</script>

<div style="font-size: 1.5em;">
  <quiet-icon library="jam" name="home"></quiet-icon>
  <quiet-icon library="jam" name="bug"></quiet-icon>
  <quiet-icon library="jam" name="bell"></quiet-icon>
  <quiet-icon library="jam" name="mic"></quiet-icon>
  <quiet-icon library="jam" name="message-alt"></quiet-icon>

  <br>

  <quiet-icon library="jam" family="filled" name="home"></quiet-icon>
  <quiet-icon library="jam" family="filled" name="bug"></quiet-icon>
  <quiet-icon library="jam" family="filled" name="bell"></quiet-icon>
  <quiet-icon library="jam" family="filled" name="mic"></quiet-icon>
  <quiet-icon library="jam" family="filled" name="message-alt"></quiet-icon>
</div>

Lucide icons Jump to heading

This example demonstrates how to load the Lucide library using the jsDelivr CDN. Only one family is available from this set.

<script type="module">
  import { registerIconLibrary } from '/dist/quiet.js';

  registerIconLibrary('lucide', {
    resolve: name => `https://cdn.jsdelivr.net/npm/lucide-static@0.344.0/icons/${name}.svg`
  });
</script>

<div style="font-size: 1.5em;">
  <quiet-icon library="lucide" name="home"></quiet-icon>
  <quiet-icon library="lucide" name="bug"></quiet-icon>
  <quiet-icon library="lucide" name="bell"></quiet-icon>
  <quiet-icon library="lucide" name="mic"></quiet-icon>
  <quiet-icon library="lucide" name="message-circle"></quiet-icon>
</div>

Myna UI icons Jump to heading

This example demonstrates how to load the Myna UI icons library using the jsDelivr CDN. Available families include outline (default) and solid.

<script type="module">
  import { registerIconLibrary } from '/dist/quiet.js';

  registerIconLibrary('myna', {
    resolve: (name, family) => {
      const folder = family === 'solid' ? 'icons-solid' : 'icons';
      return `https://cdn.jsdelivr.net/npm/@mynaui/icons@0.3.2/${folder}/${name}.svg`;
    }
  });
</script>

<div style="font-size: 1.5em;">
  <quiet-icon library="myna" name="home"></quiet-icon>
  <quiet-icon library="myna" name="daze-ghost"></quiet-icon>
  <quiet-icon library="myna" name="bell"></quiet-icon>
  <quiet-icon library="myna" name="microphone"></quiet-icon>
  <quiet-icon library="myna" name="message"></quiet-icon>

  <br>

  <quiet-icon library="myna" name="home" family="solid"></quiet-icon>
  <quiet-icon library="myna" name="daze-ghost" family="solid"></quiet-icon>
  <quiet-icon library="myna" name="bell" family="solid"></quiet-icon>
  <quiet-icon library="myna" name="microphone" family="solid"></quiet-icon>
  <quiet-icon library="myna" name="message" family="solid"></quiet-icon>  
</div>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-icon> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/components/icon/icon.js';

To manually import <quiet-icon> from npm, use the following code.

import '@quietui/quiet/dist/components/icon/icon.js';

Properties Jump to heading

Icon has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`library`	The name of the icon library to use.	`string`	`'default'`
`family`	The icon family to use for this icon, e.g. `filled` or `outline`.	`string`	`'outline'`
`name`	The name of the icon to render.	`string`
`label`	A label to use for assistive devices. If omitted, the icon will be considered presentational.	`string`

Methods Jump to heading

Icon supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name	Description	Arguments
`load()`	Loads or reloads and draws the icon.

Events Jump to heading

Icon dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`quiet-loaded`	The icon has reloaded and rendered. This event does not bubble.
`quiet-load-error`	The icon failed to load. This event does not bubble.

CSS parts Jump to heading

Icon exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`svg`	The internal SVG element.	`::part(svg)`

Icon

Examples Jump to heading #

Built-in icons Jump to heading #

Setting the icon family Jump to heading #

Labeling icons Jump to heading #

Changing the size Jump to heading #

Changing the stroke Jump to heading #

Changing the color Jump to heading #

Registering icon libraries Jump to heading #

Changing the default icon library Jump to heading #

Changing the system icon library Jump to heading #

Bootstrap icons Jump to heading #

Boxicons Jump to heading #

Jam icons Jump to heading #

Lucide icons Jump to heading #

Myna UI icons Jump to heading #

API Jump to heading #

Importing Jump to heading #

Properties Jump to heading #

Methods Jump to heading #

Events Jump to heading #

CSS parts Jump to heading #