alfresco-ng2-components/docs/core/components/icon.component.md

Title, Added, Status, Last reviewed

Title	Added	Status	Last reviewed
Icon Component	v3.0.0	Active	2025-12-11

Icon Component

Provides a universal way of rendering registered and named icons.

Basic usage

<!-- Font ligature -->
<adf-icon value="alert"></adf-icon>

<!-- ADF Thumbnail Service -->
<adf-icon value="image/png"></adf-icon>

<!-- Custom icon from MatIconRegistry -->
<adf-icon value="my-company:my-icon"></adf-icon>

Class members

Properties

Name	Type	Default value	Description
color	ThemePalette		Theme color palette for the component.
fontSet	string		Icon font set.
value	string		Icon value, which can be either a ligature name or a custom icon in the format [namespace]:[name].
isSvg	boolean	false	Is icon of type svg.

Details

You can register custom SVG files as named icons in the format [namespace]:[name].

The example below shows how to register a new icon named adf:move_file that points to an external file within the assets folder:

import { Component, OnInit } from '@angular/core';
import { MatIconRegistry } from '@angular/material/icon';
import { DomSanitizer } from '@angular/platform-browser';

@Component({...})
export class AppComponent implements OnInit {

    constructor(
        private matIconRegistry: MatIconRegistry,
        private sanitizer: DomSanitizer
    ) {}

    ngOnInit() {
        this.matIconRegistry.addSvgIconInNamespace(
            'adf',
            'move_file',
            this.sanitizer.bypassSecurityTrustResourceUrl(
                './assets/images/adf-move-file-24px.svg'
            )
        );
    }
}

In the HTML, you can now use the icon as shown below:

<adf-icon value="adf:move_file"></adf-icon>

Thumbnail Service

You can also reference the icons registered with the Thumbnail Service using the adf: namespace.

<adf-icon value="adf:image/gif"></adf-icon>

Icon alias mapping

The Icon Alias Mapping feature allows you to provide custom icon value mappings at runtime using the ICON_ALIAS_MAP_TOKEN injection token. When an icon value matches a key in the alias map, the component automatically replaces it with the mapped value. This is useful for creating consistent icon conventions across your application without modifying component code.

How icon name replacement works:

When you provide an alias map, the component checks if the icon value matches any key in the map. If a match is found, the icon name is replaced with the corresponding mapped value. This happens automatically and transparently:

• Original icon name: icon-mock
• Alias map entry: 'icon-mock': 'alias-mock'
• Result: Icon renders as alias-mock instead of icon-mock

This allows you to:

• Rename icons without changing component code
• Support legacy icon names by mapping them to new ones
• Centralize icon naming conventions in your application
• Create icon aliases for shorter or more descriptive names

Example alias map:

import { ICON_ALIAS_MAP_TOKEN } from '@alfresco/adf-core';

function getProviders() {
    return [
        {
            provide: ICON_ALIAS_MAP_TOKEN,
            useValue: {
                'icon-mock': 'alias-mock',
                'old-icon': 'new-icon'
            }
        }
    ]
}

Template usage

The Icon Component supports two ways to provide the icon value:

1. Using the value input property:

<adf-icon value="home"></adf-icon>
<adf-icon value="alert"></adf-icon>
<adf-icon value="adf:custom-icon"></adf-icon>

2. Using content projection (slot):

Similar to Angular Material's mat-icon, you can provide the icon value as text content:

<adf-icon>home</adf-icon>
<adf-icon>alert</adf-icon>
<adf-icon>adf:custom-icon</adf-icon>

Priority: If both are provided, the slot content takes priority over the value input property:

<!-- Uses "home" from slot, ignores value input -->
<adf-icon value="alert">home</adf-icon>

This approach provides flexibility and familiarity for developers accustomed to Angular Material's icon component API.

See also

• Thumbnail service