API for icon

API reference for Angular Material icon

import {MatIconModule} from '@angular/material/icon';

Service to register and display icons used by the <mat-icon> component.

  • Registers icon URLs by namespace and name.
  • Registers icon set URLs by namespace.
  • Registers aliases for CSS classes, for use with icon fonts.
  • Loads icons from URLs and extracts individual icons from icon sets.

Methods
addSvgIcon

Registers an icon by URL in the default namespace.

Parameters

iconName

string

Name under which the icon should be registered.

url

SafeResourceUrl

options?

IconOptions

Returns
this

addSvgIconInNamespace

Registers an icon by URL in the specified namespace.

Parameters

namespace

string

Namespace in which the icon should be registered.

iconName

string

Name under which the icon should be registered.

url

SafeResourceUrl

options?

IconOptions

Returns
this

addSvgIconLiteral

Registers an icon using an HTML string in the default namespace.

Parameters

iconName

string

Name under which the icon should be registered.

literal

SafeHtml

SVG source of the icon.

options?

IconOptions

Returns
this

addSvgIconLiteralInNamespace

Registers an icon using an HTML string in the specified namespace.

Parameters

namespace

string

Namespace in which the icon should be registered.

iconName

string

Name under which the icon should be registered.

literal

SafeHtml

SVG source of the icon.

options?

IconOptions

Returns
this

addSvgIconResolver

Registers an icon resolver function with the registry. The function will be invoked with the name and namespace of an icon when the registry tries to resolve the URL from which to fetch the icon. The resolver is expected to return a SafeResourceUrl that points to the icon, an object with the icon URL and icon options, or null if the icon is not supported. Resolvers will be invoked in the order in which they have been registered.

Parameters

resolver

IconResolver

Resolver function to be registered.

Returns
this

addSvgIconSet

Registers an icon set by URL in the default namespace.

Parameters

url

SafeResourceUrl

options?

IconOptions

Returns
this

addSvgIconSetInNamespace

Registers an icon set by URL in the specified namespace.

Parameters

namespace

string

Namespace in which to register the icon set.

url

SafeResourceUrl

options?

IconOptions

Returns
this

addSvgIconSetLiteral

Registers an icon set using an HTML string in the default namespace.

Parameters

literal

SafeHtml

SVG source of the icon set.

options?

IconOptions

Returns
this

addSvgIconSetLiteralInNamespace

Registers an icon set using an HTML string in the specified namespace.

Parameters

namespace

string

Namespace in which to register the icon set.

literal

SafeHtml

SVG source of the icon set.

options?

IconOptions

Returns
this

classNameForFontAlias

Returns the CSS class name associated with the alias by a previous call to registerFontClassAlias. If no CSS class has been associated, returns the alias unmodified.

Parameters

alias

string

Returns
string

getDefaultFontSetClass

Returns the CSS classes to be used for icon fonts when an <mat-icon> component does not have a fontSet input value, and is not loading an icon by name or URL.

Returns
string[]

getNamedSvgIcon

Returns an Observable that produces the icon (as an <svg> DOM element) with the given name and namespace. The icon must have been previously registered with addIcon or addIconSet; if not, the Observable will throw an error.

Parameters

name

string

Name of the icon to be retrieved.

namespace

string = ''

Namespace in which to look for the icon.

Returns
Observable<SVGElement>

getSvgIconFromUrl

Returns an Observable that produces the icon (as an <svg> DOM element) from the given URL. The response from the URL may be cached so this will not always cause an HTTP request, but the produced element will always be a new copy of the originally fetched icon. (That is, it will not contain any modifications made to elements previously returned).

Parameters

safeUrl

SafeResourceUrl

URL from which to fetch the SVG icon.

Returns
Observable<SVGElement>

registerFontClassAlias

Defines an alias for CSS class names to be used for icon fonts. Creating an matIcon component with the alias as the fontSet input will cause the class name to be applied to the <mat-icon> element.

If the registered font is a ligature font, then don't forget to also include the special class mat-ligature-font to allow the usage via attribute. So register like this:

iconRegistry.registerFontClassAlias('f1', 'font1 mat-ligature-font');

And use like this:

<mat-icon fontSet="f1" fontIcon="home"></mat-icon>
Parameters

alias

string

Alias for the font.

classNames

string = alias

Class names override to be used instead of the alias.

Returns
this

setDefaultFontSetClass

Sets the CSS classes to be used for icon fonts when an <mat-icon> component does not have a fontSet input value, and is not loading an icon by name or URL.

Parameters

...classNames

string[]

Returns
this

Component to display an icon. It can be used in the following ways:

  • Specify the svgIcon input to load an SVG icon from a URL previously registered with the addSvgIcon, addSvgIconInNamespace, addSvgIconSet, or addSvgIconSetInNamespace methods of MatIconRegistry. If the svgIcon value contains a colon it is assumed to be in the format "[namespace]:[name]", if not the value will be the name of an icon in the default namespace. Examples: <mat-icon svgIcon="left-arrow"></mat-icon> <mat-icon svgIcon="animals:cat"></mat-icon>

  • Use a font ligature as an icon by putting the ligature text in the fontIcon attribute or the content of the <mat-icon> component. If you register a custom font class, don't forget to also include the special class mat-ligature-font. It is recommended to use the attribute alternative to prevent the ligature text to be selectable and to appear in search engine results. By default, the Material icons font is used as described at http://google.github.io/material-design-icons/#icon-font-for-the-web. You can specify an alternate font by setting the fontSet input to either the CSS class to apply to use the desired font, or to an alias previously registered with MatIconRegistry.registerFontClassAlias. Examples: <mat-icon fontIcon="home"></mat-icon> <mat-icon>home</mat-icon> <mat-icon fontSet="myfont" fontIcon="sun"></mat-icon> <mat-icon fontSet="myfont">sun</mat-icon>

  • Specify a font glyph to be included via CSS rules by setting the fontSet input to specify the font, and the fontIcon input to specify the icon. Typically the fontIcon will specify a CSS class which causes the glyph to be displayed via a :before selector, as in https://fontawesome-v4.github.io/examples/ Example: <mat-icon fontSet="fa" fontIcon="alarm"></mat-icon>

Selector: mat-icon

Exported as: matIcon
Properties
Name Description
@Input()

color: string

Theme color of the icon. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.io/components/icon/styling.

For information on applying color variants in M3, see https://material.angular.io/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants

@Input()

fontIcon: string

Name of an icon within a font set.

@Input()

fontSet: string

Font set that the icon is a part of.

@Input({ transform: booleanAttribute })

inline: boolean

Whether the icon should be inlined, automatically sizing the icon to match the font size of the element the icon is contained in.

@Input()

svgIcon: string

Name of the icon in the SVG icon set.

Default options for mat-icon.

Properties
Name Description

color: ThemePalette

Theme color of the icon. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.io/components/icon/styling.

For information on applying color variants in M3, see https://material.angular.io/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants

fontSet: string

Font set that the icon is a part of.

Options that can be used to configure how an icon or the icons in an icon set are presented.

Properties
Name Description

viewBox: string

View box to set on the icon.

withCredentials: boolean

Whether or not to fetch the icon or icon set using HTTP credentials.

Object that specifies a URL from which to fetch an icon and the options to use for it.

Properties
Name Description

options: IconOptions

url: SafeResourceUrl

Function that will be invoked by the icon registry when trying to resolve the URL from which to fetch an icon. The returned URL will be used to make a request for the icon.

type IconResolver = (name: string, namespace: string) => SafeResourceUrl | SafeResourceUrlWithIconOptions | null;

Injection token to be used to override the default options for mat-icon.

const MAT_ICON_DEFAULT_OPTIONS: InjectionToken<MatIconDefaultOptions>;

API reference for Angular Material icon-testing

import {MatIconTestingModule} from '@angular/material/icon/testing';

A null icon registry that must be imported to allow disabling of custom icons.

Methods
addSvgIcon
Returns
this

addSvgIconInNamespace
Returns
this

addSvgIconLiteral
Returns
this

addSvgIconLiteralInNamespace
Returns
this

addSvgIconResolver
Returns
this

addSvgIconSet
Returns
this

addSvgIconSetInNamespace
Returns
this

addSvgIconSetLiteral
Returns
this

addSvgIconSetLiteralInNamespace
Returns
this

classNameForFontAlias
Parameters

alias

string

Returns
string

getDefaultFontSetClass
getNamedSvgIcon
Returns
Observable<SVGElement>

getSvgIconFromUrl
Returns
Observable<SVGElement>

registerFontClassAlias
Returns
this

setDefaultFontSetClass
Returns
this

Harness for interacting with a standard mat-icon in tests.

Properties
Name Description

static hostSelector: '.mat-icon'

The selector for the host element of a MatIcon instance.

Methods
async
getName

Gets the name of the icon.

Returns
Promise<string | null>

async
getNamespace

Gets the namespace of the icon.

Returns
Promise<string | null>

async
getType

Gets the type of the icon.

Returns
Promise<IconType>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
isInline

Gets whether the icon is inline.

Returns
Promise<boolean>

static
with

Gets a HarnessPredicate that can be used to search for a MatIconHarness that meets certain criteria.

Parameters

options

IconHarnessFilters = {}

Options for filtering which icon instances are considered a match.

Returns
HarnessPredicate<MatIconHarness>

a HarnessPredicate configured with the given options.

A set of criteria that can be used to filter a list of MatIconHarness instances.

Properties
Name Description

name: string | RegExp

Filters based on the name of the icon.

namespace: string | null | RegExp

Filters based on the namespace of the icon.

type: IconType

Filters based on the typef of the icon.

Azure & Blue theme selected.