Icon

The Ignite UI for Web Components Icon is a component that renders a named icon from a registered icon set, such as a collection of custom SVG icons.

Register SVG icons by name in a collection, then display each icon at a theme-based size in the color of the surrounding text.

Live Demo

Anatomy

An icon is a symbol representing a command, device, directory, or common action.

The Web Components Icon renders an igc-icon element, which draws the registered SVG in its shadow root and exposes no CSS parts:

igc-icon                 // host - inline box sized by --size
└─ #shadow-root
   └─ svg                // the registered SVG, 1em × 1em, filled with the current color

Getting Started

To use the Web Components Icon, follow the Ignite UI for Web Components Getting Started topic for the basic project setup, then add the component for your target platform.

Install the igniteui-webcomponents package:

npm install igniteui-webcomponents

Then import the Icon, its theme CSS, and register the component:

import { defineComponents, IgcIconComponent } from 'igniteui-webcomponents';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

defineComponents(IgcIconComponent);

After registration, render the Icon with an icon name and a collection:

<igc-icon name="search" collection="material"></igc-icon>

The icon stays empty until you register an SVG icon under the same name and collection, as described in Name and Collection.

Usage

Use the Web Components Icon to add a recognizable symbol to labels, buttons, list items, and navigation, or to show a status at a glance.

Name and Collection

The Web Components Icon draws the SVG that is registered under its name in its collection. The collection defaults to default. All icons on the page share one registry, so an icon that you register once is available to every Icon, and an Icon that renders before its SVG is registered updates as soon as you register it.

Register SVG markup with registerIconFromText, or fetch an SVG file from a URL with registerIcon:

import { registerIcon, registerIconFromText } from 'igniteui-webcomponents';

const searchIcon =
  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"/></svg>';

registerIconFromText('search', searchIcon, 'material');
registerIcon('build', '/icons/build.svg', 'material');

Then set the same name and collection on each icon:

<igc-icon name="search" collection="material"></igc-icon>
<igc-icon name="build" collection="material"></igc-icon>

Icon References

An icon reference points an icon name to another registered icon. Components such as the Combo and the Date Picker render their built-in icons through references in the default collection, and a reference that you set takes precedence over them. For example, point the input_clear reference to your own icon to replace the clear icon of these two components:

import { registerIconFromText, setIconRef } from 'igniteui-webcomponents';

const closeIcon =
  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>';

registerIconFromText('close', closeIcon, 'my-icons');
setIconRef('input_clear', 'default', { name: 'close', collection: 'my-icons' });

Size

The Web Components Icon supports the small, medium, and large size presets of the theme, and uses the large preset by default. Set the --ig-size CSS variable to --ig-size-small, --ig-size-medium, or --ig-size-large to choose a preset:

.small {
  --ig-size: var(--ig-size-small);
}

.medium {
  --ig-size: var(--ig-size-medium);
}

<igc-icon class="small" name="build" collection="material"></igc-icon>

For a size outside the presets, set --size on the icon. To resize all icons inside a container, set --ig-icon-size on the container:

.custom-size {
  --size: 56px;
}

.toolbar {
  --ig-icon-size: 2rem;
}

Mirrored

Set mirrored to flip the icon horizontally. Use it for directional icons, such as arrows, in right-to-left layouts.

<igc-icon name="arrow_forward" collection="material" mirrored></igc-icon>

Accessible Name

Hide a decorative icon from assistive technology, and give an icon that conveys meaning on its own an accessible name that describes that meaning.

Set aria-label on the icon to name it. The <title> element of a registered SVG also names the icon. Set aria-hidden="true" on a decorative icon next to visible text:

<igc-icon name="warning" collection="material" aria-label="Warning"></igc-icon>

<span>
  <igc-icon name="search" collection="material" aria-hidden="true"></igc-icon>
  Search
</span>

Do/Don’t

Carefully pick the Icon color to assure good contrast with the background and definitely avoid similar shades of the same color or combinations that create chromatic aberrations.

Properties

The Web Components Icon exposes the following properties. See the API reference for the complete type definitions.

Methods

The Web Components Icon draws icons that you register with the following API.

Register icons with the following functions, which you import from igniteui-webcomponents. Pass a RegisterIconOptions object instead of the collection name to set the collection and stripMeta options together.

Styling

The Web Components Icon takes the color of the surrounding text by default. Change its color and size with the following CSS variables:

The igc-icon element exposes no CSS parts, so apply the styles to the element itself.

Sass Theming

Create a theme with the icon-theme function and include it with the tokens() mixin. The function accepts the $color, $size, and $disabled-color parameters, and the mixin emits the matching --ig-icon-* variables in the scope where you include it.

The Sass functions come from the igniteui-theming package. See the Theming topic for the Sass setup.

@use "igniteui-theming" as *;

$custom-icon-theme: icon-theme(
  $color: #1481b8
);

:root {
  @include tokens($custom-icon-theme);
}

CSS Variables

Set the color and size on an icon or a container when you need local styling without a Sass build step:

igc-icon {
  --size: 28px;
  color: var(--ig-primary-500);
}

.toolbar {
  --ig-icon-color: var(--ig-primary-500);
}

Styling with Tailwind

You can style the Web Components Icon with the custom Tailwind utility classes from igniteui-theming. Make sure to set up Tailwind first, then import the Ignite UI utilities in your global stylesheet:

@import "tailwindcss";
@import "igniteui-theming/tailwind/utilities/material.css";

Use the light-icon or dark-icon class for the corresponding theme, and override the generated CSS variables with arbitrary properties:

<igc-icon name="search" collection="material" class="!light-icon ![--color:#7B9E89] ![--size:48px]"></igc-icon>

The exclamation mark (!) gives the Tailwind utility precedence over the default theme styles of the Icon.

Accessibility

The Web Components Icon is a non-interactive visual that either decorates nearby content or conveys meaning on its own.

Keyboard Interaction

The Web Components Icon doesn’t receive focus and has no keyboard interaction: it sets no tabindex and handles no keyboard or pointer events. Use the Icon Button when users must activate an icon with the keyboard.

Screen Readers / ARIA

The Web Components Icon makes no announcements of its own. What assistive technology reports depends on the accessible name of the icon:

• The icon sets its role and accessible name through element internals, not through attributes on the igc-icon element.
• A <title> element that is a direct child of the root <svg> of the registered icon becomes the accessible name of the icon.
• An aria-label or aria-labelledby attribute on the icon names an icon whose SVG has no title, and takes precedence over the title.
• With igniteui-webcomponents 7.3.0 and later, the icon declares the img role only when it has an accessible name, so an icon without a name isn’t exposed as an unnamed image.
• The icon checks for an accessible name when it resolves its SVG: when name or collection changes, when the theme changes, or when an icon is registered. Set aria-label or aria-labelledby in the initial markup.
• The stripMeta registration option removes the <title> and <desc> elements from the stored SVG, but the icon keeps the title text as its accessible name.

Accessibility Compliance

Infragistics documents Ignite UI for Web Components accessibility support for Section 508 and WCAG 2.1 guideline areas in the Accessibility Compliance topic.

Your responsibilities:

• Give every icon that conveys meaning on its own an accessible name, and keep decorative icons hidden. See Accessible Name.
• Keep a contrast ratio of at least 3:1 between an icon that conveys information and its background, as 1.4.11 Non-text Contrast requires, especially when you override the theme color.
• Use an Icon Button, not an Icon, for actions that users activate.
• Set mirrored on directional icons in right-to-left layouts so that their direction matches the reading order.

Troubleshooting

Use these answers when a Web Components Icon doesn’t render or doesn’t look as expected.

Why is my icon empty?

The Web Components Icon draws only an SVG that is registered under the same name and collection. Check the following causes:

• The name or the collection doesn’t match the registration exactly. The collection defaults to default.
• The SVG markup is malformed. Registration throws the SVG element not found or malformed SVG string. error when the text has no root <svg> element or doesn’t parse.
• The request for an SVG file failed. The registration from a URL fails for a non-OK response, so check the browser console and the network panel. A file on another origin also needs a server that allows cross-origin requests.

During server-side rendering, the icon renders no SVG. It draws the SVG after it loads in the browser.

Why doesn’t my SVG icon take the theme color?

The Web Components Icon applies its color to the root <svg> element, and the child elements inherit it as their fill. A child element with a hardcoded color keeps that color:

<svg viewBox="0 0 24 24">
  <path fill="#050d42" d="..." />
</svg>

Remove hardcoded colors from the child elements, or set the color on the root <svg> element, where the theme overrides it. To color part of an icon on purpose, use a theme color variable, such as fill="var(--ig-primary-500)".

Why does a tooltip appear when I hover an icon?

Browsers show the <title> element of an SVG as a native tooltip.

Register the icon with the stripMeta option to remove the <title> and <desc> elements from the stored SVG. The icon keeps the title text as its accessible name:

registerIconFromText('search', searchIcon, { collection: 'material', stripMeta: true });

Known Limitations

The Web Components Icon has the following limitations:

• The Icon is a non-interactive visual: it doesn’t receive focus or handle keyboard input.
• Theme colors reach the root <svg> element and the child elements that inherit its fill. Child elements with hardcoded colors keep them.
• The Icon draws registered SVG icons only. Icon fonts and ligatures aren’t supported.

API References

Dependencies

The Web Components Icon requires a theme stylesheet to apply its theme-based size and color. See the framework-specific setup in Getting Started.

Additional Resources

The following resources provide more Web Components Icon guidance and project support:

• Icon - Design System Component
• Ignite UI for Web Components Forums
• Ignite UI for Web Components GitHub

Related Components

The Web Components Icon often appears inside other components. Use these components when an icon needs to do more than display a symbol:

• Icon Button - Use Icon Button when users click or press the icon to run an action.
• Avatar - Use Avatar to represent a person or entity with an icon, initials, or an image.
• Badge - Use Badge to show a short status or count next to another element.

FAQ

These questions cover common Web Components Icon setup, accessibility, and usage scenarios.