Infragistics
Close
Angular React Web Components Blazor Angular
Open Source

Icon

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

By default, the Angular Icon renders Material Icons ligatures. Register SVG icons and other icon fonts with the IgxIconService to use them the same way.

Live Demo

Anatomy

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

Icon anatomy showing the icon glyph
1. Icon: a visual symbol used to represent actions, objects or ideas

The igx-icon element renders one of the following, depending on the type of its icon family:

igx-icon.igx-icon[aria-hidden="true"]   // host - also carries the family class, e.g. .material-icons
├─ ligature text                        // `liga` family - the icon name, e.g. home
├─ div > svg                            // SVG icon registered with IgxIconService
└─ ng-content                           // projected ligature text when `name` isn't set

For a font family, the classes on the host draw the glyph, and the element has no content.

Getting Started

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

If your project doesn’t use Ignite UI for Angular yet, run ng add igniteui-angular. Then import the standalone Icon and add it to the imports of your component:

import { Component } from '@angular/core';
import { IgxIconComponent } from 'igniteui-angular/icon';

@Component({
    selector: 'app-home',
    template: '<igx-icon name="home"></igx-icon>',
    imports: [IgxIconComponent]
})
export class HomeComponent {}

The home name is a Material Icons ligature, so the icon appears as soon as the Material Icons font loads.

Usage

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

Name and Family

The Angular Icon looks up its name in its family. The default material family renders Material Icons ligatures, so the name is the ligature, such as home or favorite:

<igx-icon name="home"></igx-icon>
<igx-icon name="favorite"></igx-icon>

You can also project the ligature as content:

<igx-icon>bluetooth</igx-icon>

SVG Icons

Register SVG icons with the IgxIconService, then set their name and family on the icon. The addSvgIcon method fetches an SVG file from a URL, and addSvgIconFromText registers SVG markup:

import { Component, OnInit, inject } from '@angular/core';
import { IgxIconComponent, IgxIconService } from 'igniteui-angular/icon';

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>';

@Component({
    selector: 'app-filter-icons',
    template: `
        <igx-icon name="contains" family="filter-icons"></igx-icon>
        <igx-icon name="search" family="filter-icons"></igx-icon>
    `,
    imports: [IgxIconComponent]
})
export class FilterIconsComponent implements OnInit {
    private iconService = inject(IgxIconService);

    public ngOnInit() {
        this.iconService.addSvgIcon('contains', 'assets/images/svg/contains.svg', 'filter-icons');
        this.iconService.addSvgIconFromText('search', searchIcon, 'filter-icons');
    }
}

When an SVG icon and a ligature share the same name and family, the icon renders the SVG.

Font Families

Use setFamily to add another icon font, such as Material Symbols, as a family. Load the font stylesheet first:

<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" rel="stylesheet" />

Map the family name to the CSS class of the font and set its type to liga:

this.iconService.setFamily('material-symbols', { className: 'material-symbols-outlined', type: 'liga' });

Then set the family on the icon. Material Symbols is a variable font, so you can adjust settings such as fill and weight:

<igx-icon family="material-symbols" name="diamond" class="custom-icon"></igx-icon>
.custom-icon {
  font-variation-settings: "FILL" 0, "wght" 200, "GRAD" 0, "opsz" 40;
}

The Icon Service topic covers families of the font type, name prefixes, and icon references.

Size

The Angular 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);
}
<igx-icon class="small" name="build"></igx-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;
}

Active

Set active to false to show the icon as inactive. An inactive icon uses the disabled color of the theme at a reduced opacity:

<igx-icon name="volume_off" [active]="false"></igx-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.

The Angular Icon is hidden from assistive technology by default, because its ariaHidden input sets aria-hidden="true". To expose an icon that conveys meaning, set ariaHidden to false, and add the img role and an aria-label:

<igx-icon name="warning" [ariaHidden]="false" role="img" aria-label="Warning"></igx-icon>

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.

White bell and orange gear icons with strong contrast against a blue background Light blue bell and dark orange gear icons with weak contrast against a blue background

Do

Pick icon colors with strong contrast against the background.

Don’t

Avoid shades similar to the background and color combinations that cause chromatic aberration.

Properties

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

Name Type Default Description
name string — The name of the icon. For a ligature family, the name is the ligature.
family string material The icon family in which the name is looked up.
active boolean true Whether the icon is active. An inactive icon uses the disabled color of the theme.
ariaHidden boolean true The value of the aria-hidden attribute of the icon.

Methods

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

Register icons and families with the following methods of the IgxIconService, which is provided in the application root.

Method Description
addSvgIcon Fetches an SVG file through HttpClient and caches it under a name in a family.
addSvgIconFromText Caches SVG markup under a name in a family.
setFamily Associates a family name with a CSS class, an icon type (liga, font, or svg), and an optional name prefix.
setIconRef Points an icon name in a family to another icon.
addIconRef Points an icon name in a family to another icon only when the name has no reference yet.

Styling

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

Variable What it changes
--ig-icon-color The icon color. Set it on an icon, or on a container to recolor all icons inside it.
--ig-icon-size The icon size. Set it on an icon, or on a container to resize all icons inside it.
--size The size of the icon on which you set it.
--ig-size The size preset: --ig-size-small, --ig-size-medium, or --ig-size-large.
--ig-icon-disabled-color The color of an inactive icon.

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.

@use "igniteui-angular/theming" as *;

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

:host {
  @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:

<igx-icon name="home" [style.color]="'#e41c77'"></igx-icon>
.toolbar {
  --ig-icon-color: var(--ig-primary-500);
}

Styling with Tailwind

You can style the Angular 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:

<igx-icon name="person" class="!light-icon ![--color:#7B9E89] ![--size:48px]"></igx-icon>

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

Accessibility

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

Keyboard Interaction

The Angular 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.

Key Action
n/a The Icon is not keyboard interactive.

Screen Readers / ARIA

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

  • The icon sets aria-hidden="true" by default through its ariaHidden input, so assistive technology ignores it. An aria-label alone doesn’t expose a hidden icon.
  • The icon sets no role. When you set ariaHidden to false without a role and a label, screen readers read a ligature icon as its text, such as home.
  • Set ariaHidden to false, add the img role, and add an aria-label to expose an icon that conveys meaning.
  • The active input changes only the styling. The inactive state isn’t exposed to assistive technology.

Accessibility Compliance

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

Criterion How the component complies
1.1.1 Non-text Content The icon is hidden from assistive technology by default, so decorative icons can be ignored, and it uses the aria-label that you set as its text alternative when you expose it.

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.
  • Don’t rely on the inactive styling alone to convey a state, as 1.4.1 Use of Color requires. Describe the state in text or in the accessible name.

Troubleshooting

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

Why is my icon empty?

Check the following causes:

  • A ligature icon needs the font of its family, such as Material Icons for the default material family. Check that the font stylesheet loads.
  • An SVG icon needs the same name and family as its registration.
  • addSvgIcon needs HttpClient to fetch the file. Check the network panel for a failed request.
  • The service caches SVG icons only in the browser, so SVG icons don’t render during server-side rendering.

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

The Angular 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.

Pass true as the stripMeta argument of addSvgIcon or addSvgIconFromText to remove the <title> and <desc> elements from the cached SVG:

this.iconService.addSvgIcon('contains', 'assets/images/svg/contains.svg', 'filter-icons', true);

Known Limitations

The Angular 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 Angular Icon has no option to mirror an icon for right-to-left layouts.

API References

Dependencies

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

Ligature icons of the default material family also require the Material Icons font, and addSvgIcon requires the Angular HttpClient.

Additional Resources

The following resources provide more Angular Icon guidance and project support:

For icon families, icon references, and the extended Material icon set, see the Icon Service and Material Icons Extended topics.

The Angular 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 Angular Icon setup, accessibility, and usage scenarios.

Does the Icon include Material Icons?

Yes. The Angular Icon renders Material Icons ligatures through its default material family when the Material Icons font is loaded, and the ng add igniteui-angular command adds that font. Register other icon fonts and SVG icons with the IgxIconService.

How do I add a custom SVG icon?

Register the SVG with the addSvgIcon or addSvgIconFromText method of the IgxIconService, then set the same name and family on the Angular Icon. The service caches the SVG, so every Angular Icon with that name and family renders it.

How do I make an icon accessible to screen readers?

The Angular Icon is hidden from screen readers by default through aria-hidden="true". For an icon that conveys meaning on its own, set [ariaHidden]="false", add role="img", and add an aria-label that describes the meaning.

Can I make an Icon clickable?

The Angular Icon doesn’t receive focus or handle keyboard input, so a click handler on it excludes keyboard users. Use the Angular Icon Button for actions, because it places an icon inside a focusable button.

Does the Icon support right-to-left layouts?

The Angular Icon has no option to mirror an icon. For a directional icon in a right-to-left layout, use an icon that points in the reading direction, such as arrow_back in place of arrow_forward.