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.
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.
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 itsariaHiddeninput, so assistive technology ignores it. Anaria-labelalone doesn’t expose a hidden icon. - The icon sets no role. When you set
ariaHiddentofalsewithout a role and a label, screen readers read a ligature icon as its text, such ashome. - Set
ariaHiddentofalse, add theimgrole, and add anaria-labelto expose an icon that conveys meaning. - The
activeinput 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
materialfamily. Check that the font stylesheet loads. - An SVG icon needs the same name and family as its registration.
addSvgIconneedsHttpClientto 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.
Related Components
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.
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.
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.
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.
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.
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.