{"_id":"@a11y-ngx/icon","_rev":"2-4031a0c89e686ebd27083c3ce1c16fd9","name":"@a11y-ngx/icon","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@a11y-ngx/icon","version":"1.0.0","keywords":["icon","html","image","component","template","wrapper","a11y","accessible","accessibility","angular"],"author":{"url":"https://github.com/LDV2k3/","name":"Luciano Del Vacchio","email":"lucho.development@gmail.com"},"license":"MPL-2.0","_id":"@a11y-ngx/icon@1.0.0","maintainers":[{"name":"ldv","email":"lucho.development@gmail.com"}],"homepage":"https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/icon#readme","bugs":{"url":"https://github.com/LDV2k3/a11y-libraries/issues","email":"lucho.development@gmail.com"},"dist":{"shasum":"ec47760016ff8f429a663c659af9806a5da2edc1","tarball":"https://registry.npmjs.org/@a11y-ngx/icon/-/icon-1.0.0.tgz","fileCount":28,"integrity":"sha512-LyY65e5t59uZmiFB/AixMklUZwbPM4ojbcNPJJ/krrmpJoyp17XoU03pm9ObGAvuHHhNrhHqj9RwhEPe+32riA==","signatures":[{"sig":"MEQCIAjLC8aNs0nB1gniPAFWJiUpTZQtk9tYvkjldajxK60PAiBKAMkNn8uRvWvqpaK3d3kW65ViK38aAeC7xnzo6MwrmA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":262772},"main":"bundles/a11y-ngx-icon.umd.js","es2015":"fesm2015/a11y-ngx-icon.js","module":"fesm2015/a11y-ngx-icon.js","esm2015":"esm2015/a11y-ngx-icon.js","gitHead":"e0d8f8af9b943ac9c3d5ae479506cd340b1bdf98","typings":"a11y-ngx-icon.d.ts","_npmUser":{"name":"ldv","email":"lucho.development@gmail.com"},"fesm2015":"fesm2015/a11y-ngx-icon.js","_npmVersion":"8.19.4","description":"A polymorphic icon wrapper that enables your Angular libraries to accept and render any icon format (HTML, images, Components, or TemplateRefs).","directories":{},"sideEffects":false,"_nodeVersion":"16.20.2","dependencies":{"tslib":"^2.3.0"},"_hasShrinkwrap":false,"peerDependencies":{"@angular/core":">=12.2.0 <22.0.0","@angular/common":">=12.2.0 <22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/icon_1.0.0_1778711584706_0.9696873939190911","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@a11y-ngx/icon","version":"1.0.1","description":"A polymorphic icon wrapper that enables your Angular libraries to accept and render any icon format (HTML, images, Components, or TemplateRefs).","keywords":["icon","html","image","component","template","wrapper","a11y","accessible","accessibility","angular"],"homepage":"https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/icon#readme","bugs":{"url":"https://github.com/LDV2k3/a11y-libraries/issues","email":"lucho.development@gmail.com"},"license":"MPL-2.0","author":{"name":"Luciano Del Vacchio","email":"lucho.development@gmail.com","url":"https://github.com/LDV2k3/"},"peerDependencies":{"@angular/common":">=12.2.0 <22.0.0","@angular/core":">=12.2.0 <22.0.0"},"dependencies":{"tslib":"^2.3.0"},"main":"bundles/a11y-ngx-icon.umd.js","module":"fesm2015/a11y-ngx-icon.js","es2015":"fesm2015/a11y-ngx-icon.js","esm2015":"esm2015/a11y-ngx-icon.js","fesm2015":"fesm2015/a11y-ngx-icon.js","typings":"a11y-ngx-icon.d.ts","sideEffects":false,"gitHead":"32ce15c16e4e01aacfe01cfb055f877f0f24a99b","_id":"@a11y-ngx/icon@1.0.1","_nodeVersion":"16.20.2","_npmVersion":"8.19.4","dist":{"integrity":"sha512-/pCYy/Fnv2JopUaVW85vCMup0GP/kkypV+Z1B/+OY4a6XTBtfqKO8UJ5LM/pW/xPDzZ+ryPcjo/jfNXd0003WA==","shasum":"b999e7380055b8832e15303310cf360e8ab13b8c","tarball":"https://registry.npmjs.org/@a11y-ngx/icon/-/icon-1.0.1.tgz","fileCount":28,"unpackedSize":263459,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDf4xnmsR/ERBcgwlCusjvWd/xTgONw8AnVPB9fLIWsoAiEA/qZIVYv85w8V5jcvlY5DeNMYKvVXc2UGvBStXLGSAQs="}]},"_npmUser":{"name":"ldv","email":"lucho.development@gmail.com"},"directories":{},"maintainers":[{"name":"ldv","email":"lucho.development@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/icon_1.0.1_1784236720071_0.4974863960758431"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-13T22:33:04.587Z","modified":"2026-07-16T21:18:40.396Z","1.0.0":"2026-05-13T22:33:04.883Z","1.0.1":"2026-07-16T21:18:40.228Z"},"bugs":{"url":"https://github.com/LDV2k3/a11y-libraries/issues","email":"lucho.development@gmail.com"},"author":{"name":"Luciano Del Vacchio","email":"lucho.development@gmail.com","url":"https://github.com/LDV2k3/"},"license":"MPL-2.0","homepage":"https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/icon#readme","keywords":["icon","html","image","component","template","wrapper","a11y","accessible","accessibility","angular"],"description":"A polymorphic icon wrapper that enables your Angular libraries to accept and render any icon format (HTML, images, Components, or TemplateRefs).","maintainers":[{"name":"ldv","email":"lucho.development@gmail.com"}],"readme":"# Icon\n\nAn Angular core utility library designed to normalize icon rendering across UI components. It provides a unified `<a11y-icon>` wrapper that seamlessly handles icons provided as raw strings, image paths, components or TemplateRefs, decoupling the rendering logic from the consuming libraries.\n\n> 👀 **IMPORTANT:** This is a low-level utility library. It is **not** meant to be used as a direct wrapper for `mat-icon` or `fa-icon` in your daily application code.\n>\n> ✨ Its primary purpose is to be consumed by **other UI component libraries** that need icons (like accessible Menus, Tree views, or Dropdowns). It provides library authors with a standardized, decoupled way to accept any icon format from the end-user, delegating the rendering strategy to the host application without forcing a specific icon pack.\n\n![Angular support from version 12 up to version 21](https://img.shields.io/badge/Angular-v12_to_v21-darkgreen?logo=angular)\n\nThis library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 12.2.0 to ensure compatibility with a wide range of Angular versions. It has been tested up to v21.\n\n## Changelog\n\nSee the complete [changelog](https://github.com/LDV2k3/a11y-libraries/blob/master/projects/a11y-ngx/icon/CHANGELOG.md) for details on updates and breaking changes.\n\n## Index\n\n- [Installation](#installation)\n- [What is a \"Strategy\"?](#what-is-a-strategy)\n- [The Global Config](#the-global-config)\n  - [The Strategy](#the-strategy)\n  - [The Base Path](#the-base-path)\n- [The Component](#the-component)\n  - [The Component Inputs](#the-component-inputs)\n    - [The Icon Input](#the-icon-input)\n    - [The Label Input](#the-label-input)\n- [Configure The Strategies](#configure-the-strategies)\n  - [Configure the Global Strategy](#configure-the-global-strategy)\n  - [Configure the Custom Strategy](#configure-the-custom-strategy)\n    - [Provide a static value](#provide-a-static-value)\n    - [Provide via Dependency Injection](#provide-via-dependency-injection)\n- [Real-World Use Case](#real-world-use-case)\n- [Examples](#examples)\n  - **Direct Inputs** (Passing values directly to the component):\n    - [Raw HTML Source](#raw-html-source)\n    - [Image Source](#image-source)\n    - [Component Source](#component-source)\n    - [TemplateRef Source](#templateref-source)\n  - **String Strategies** (Resolving string values via providers):\n    - [Component Strategy](#component-strategy)\n    - [Image Strategy](#image-strategy)\n    - [Template Strategy](#template-strategy)\n\n## Installation\n\n1. Install npm package:\n\n   `npm install @a11y-ngx/icon --save`\n\n2. Import `A11yIconModule` into your module or standalone component:\n\n   ```typescript\n   import { A11yIconModule } from '@a11y-ngx/icon';\n\n   @NgModule({\n       declarations: [...],\n       imports: [\n           ...\n           A11yIconModule,\n       ],\n   })\n   export class AppModule {}\n   ```\n\n## What is a \"Strategy\"?\n\nYou can provide different types of icons to the `<a11y-icon>` component: strings, components or TemplateRefs.\n\nWhen you pass a simple string (e.g., `icon=\"home\"` or `icon=\"/assets/icon-home.png\"`), the library needs to know how to render it. By default, a string will be rendered as raw HTML (using `innerHTML`).\n\nThe strategy defines the _default wrapper_ for that string:\n\n- `IconDefaultComponent` (e.g., `MatIcon`): The string will be used (via input or content projection) inside the given component:\n\n  > ```html\n  > <!-- Input: -->\n  > <a11y-icon icon=\"home\"></a11y-icon>\n  > <!-- Output: In this case, Material Icon uses content projection -->\n  > <mat-icon>home</mat-icon>\n  > ```\n\n- `'image'`: The string will be treated as a path/URL and bound to an image tag:\n\n  > ```html\n  > <!-- Input: -->\n  > <a11y-icon icon=\"/assets/icons/home.png\"></a11y-icon>\n  > <!-- Output: -->\n  > <img src=\"/assets/icons/home.png\" alt=\"\">\n  > ```\n\n- `TemplateRef`: The string will be used as its implicit context.\n\n> 🛠️ Check [how to configure the strategies](#configure-the-strategies).\n\n## The Global Config\n\nUse the `rootConfig()` method or `provideA11yIcon` to establish the global behavior for your icons across the entire application.\n\n> ⚠️ **IMPORTANT: ❗❗ DO NOT use it on a library or a low-level module/component within your app**, since this method is meant to be called **only once** at a root level on the **main app**.\n>\n> On a library, sub-module or component, check [how to provide the custom strategy](#configure-the-custom-strategy).\n\n- **Type:** `IconConfig`\n- **Properties:**\n  - [`strategy`](#the-strategy)\n  - [`basePath`](#the-base-path)\n\n### The Strategy\n\nSee [how to configure the Global Strategy](#configure-the-global-strategy).\n\n### The Base Path\n\nIf you are using the [Image Strategy](#image-strategy) to load local or external images, you can define a `basePath` in your global configuration object. This prefix will be automatically prepended to all your icon strings, keeping your HTML templates clean and avoiding repetitive folder paths.\n\n**On Angular v12 - v14:**\n\n```typescript\nimport { MatIcon } from '@angular/material/icon';\nimport { A11yIconModule } from '@a11y-ngx/icon';\n\n@NgModule({\n    ...,\n    imports: [\n        A11yIconModule.rootConfig({\n            strategy: 'image',\n            basePath: '/assets/icons/',\n        }),\n    ],\n})\nexport class AppModule {}\n```\n\n**On Angular v15+:**\n\n```typescript\nimport { provideA11yIcon } from '@a11y-ngx/icon';\n\nexport const appConfig: ApplicationConfig = {\n    ...,\n    providers: [\n        provideA11yIcon({\n            strategy: 'image',\n            basePath: '/assets/icons/',\n        }),\n    ],\n};\n```\n\n**Template:**\n\n```html\n<!-- ❌ Without \"basePath\": -->\n<a11y-icon icon=\"/assets/icons/settings.svg\"></a11y-icon>\n\n<!-- ✔️ With \"basePath\" configured: -->\n<a11y-icon icon=\"settings.svg\"></a11y-icon>\n```\n\n> 💡 If you need to bypass the global `basePath` for a specific icon, you can use the `ignoreBasePath` property within the `IconInputImage` object:\n>\n> ```html\n> <a11y-icon\n>     [icon]=\"{\n>         src: '/assets/another-folder/settings.svg',\n>         ignoreBasePath: true\n>     }\">\n> </a11y-icon>\n> ```\n\n## The Component\n\nThe core of this library is the `<a11y-icon>` component. It acts as a universal wrapper designed to easily render any icon type, keeping your components independent from specific icon packs like Material or FontAwesome.\n\n**Key capabilities:**\n\n- **Polymorphic Input:** Seamlessly renders raw HTML, `Component`s, `TemplateRef`s, or static images.\n  - 💡 Even with a strategy set, you can override the rendered type per-instance on the fly. Just pass the corresponding object payload (`IconInputImage`, `IconInputComponent`, etc.) to the input and the component will adapt automatically.\n- **Global Strategies:** Automatically falls back to your configured global or custom strategy when receiving simple strings.\n- **A11y Ready:** Provides sensible accessibility defaults (like `aria-hidden=\"true\"`) for decorative icons, while fully supporting custom `aria-label` and `role=\"img\"` for meaningful ones.\n\n> 💡 **Icon Sizing:**\n>\n> By default, the component sets the icon size to `1rem` using a CSS variable. You can easily override this behavior by redefining the `--icon-size` variable at any level of your DOM tree.\n>\n> 1. **Global Override:**<br />\n> Set it in your global stylesheet to change the default size for the entire application.\n>\n>    ```css\n>    :root {\n>        --icon-size: 24px;\n>    }\n>    ```\n>\n> 2. **Scoped Override:**<br />\n> Apply it to a parent container to affect all icons inside it.\n>\n>    ```html\n>    <div class=\"my-toolbar\" style=\"--icon-size: 1.5rem;\">\n>        <a11y-icon icon=\"edit\"></a11y-icon>\n>        <a11y-icon icon=\"delete\"></a11y-icon>\n>    </div>\n>    ```\n\n### The Component Inputs\n\n| Name | Type | Description |\n| :--- | :--- | :---------- |\n| `icon` | `Icon` | See [the Icon Input](#the-icon-input) |\n| `label` | `string` | See [the Label Input](#the-label-input) |\n\n#### The Icon Input\n\nThe core payload to be rendered.\n\n- **Input:** `icon`\n- **Type:** `Icon`, which accepts:\n  - `string`: Renders as raw HTML or according to the [active strategy](#what-is-a-strategy).\n  - `IconInputHTML`: Renders the given text as raw HTML.\n\n    > ```typescript\n    > { html: '<i class=\"fa-solid fa-star\"></i>' }\n    > ```\n\n  - `IconInputImage`: Renders a standard `<img>` tag pointing to the given path.\n\n    > ```typescript\n    > { src: '/assets/icons/star.png' }\n    > ```\n\n  - `IconInputComponent`: Dynamically instantiates the provided Angular Component.\n\n    > ```typescript\n    > // For \"content projection\" components:\n    > { component: MatIcon, content: 'info' }\n    > // For \"input\" components:\n    > { component: AppIconComponent, inputs: { icon: 'fa-solid fa-info' } }\n    > ```\n\n  - `IconInputTemplate`: Renders the provided `<ng-template>`.\n\n#### The Label Input\n\nAn optional string to define the accessible name for meaningful (informative) icons.\n\n- **Input:** `label`\n- **Type:** `string`\n\n> ✔️ **When provided:** It applies the `aria-label` attribute to the icon, ensuring it is properly announced by screen readers.\n>\n> ❌ **When omitted:** The component assumes the icon is purely decorative and automatically applies `aria-hidden=\"true\"` to hide it from assistive technologies.\n>\n> Check [the TemplateRef Source example](#templateref-source).\n\n## Configure The Strategies\n\nYou can configure the strategy globally or locally (custom).\n\n💡 Please check the section [what is a \"strategy\"?](#what-is-a-strategy)\n\n> 👉 **REMEMBER:** When a strategy is defined, the `string` value set in the `icon` input acts as its _main value_.\n>\n> There are three types of strategies:\n>\n> - `IconDefaultComponent` (object): The string will be used (via input or content projection) inside the given component.\n>\n>   | Property | Type | Mandatory | Description |\n>   | :------- | :--- | :-------: | :---------- |\n>   | `component` | `Type<unknown>` | ✔️ Yes | The main target component |\n>   | `mainEntry` | `'input'` or `'content'` | ✔️ Yes | How the target component receives the icon value |\n>   | `inputName` | `string` | Only for `mainEntry='input'` | The input that receives the icon's string |\n>   | `inputs` | `Record<string, unknown>` | ❌ No | Any inputs the component might need |\n>\n> - `IconInputTemplate` (aka `TemplateRef<unknown>`): The string will be used as its implicit context. ⚠️ _(Only available for custom strategies, not global)_\n> - `'image'`: The string will be treated as a path/URL and bound to an image tag.\n\n### Configure the Global Strategy\n\n> ⚠️ **REMEMBER: ❗❗ App-level use only!** Must be called at the root.\n>\n> On a library, sub-module or component, check [how to provide the custom strategy](#configure-the-custom-strategy).\n\nAccepts a single parameter `config` of type [`IconConfig`](#the-global-config).\n\n**On Angular v12 - v14:**\n\n```typescript\nimport { MatIcon } from '@angular/material/icon';\nimport { A11yIconModule } from '@a11y-ngx/icon';\n\n@NgModule({\n    ...,\n    imports: [\n        A11yIconModule.rootConfig({\n            strategy: {\n                component: MatIcon,\n                mainEntry: 'content',\n            },\n        }),\n    ],\n})\nexport class AppModule {}\n```\n\n**On Angular v15+:**\n\n```typescript\nimport { MatIcon } from '@angular/material/icon';\nimport { provideA11yIcon } from '@a11y-ngx/icon';\n\nexport const appConfig: ApplicationConfig = {\n    ...,\n    providers: [\n        provideA11yIcon({\n            strategy: {\n                component: MatIcon,\n                mainEntry: 'content',\n            },\n        }),\n    ],\n};\n```\n\n### Configure the Custom Strategy\n\nThe custom strategy is meant to be used in libraries, low-level modules or components to scope all its children.\n\n> ⚠️ It will override the global strategy, if any.\n\nAccepts two parameters:\n\n- `factory` of type `(args) => IconDefaultComponent | IconInputTemplate | 'image'`.\n- `deps` _(optional)_ of type `any[]`.\n\n#### Provide a static value\n\n```typescript\nimport { provideCustomA11yIcon } from '@a11y-ngx/icon';\n\n@Component({\n    ...,\n    providers: [\n        provideCustomA11yIcon(() => 'image'),\n    ],\n})\nexport class MyComponent {}\n```\n\n#### Provide via Dependency Injection\n\n**On Angular v12 - v14:**\n\n```typescript\nimport { provideCustomA11yIcon } from '@a11y-ngx/icon';\n\n@Component({\n    ...,\n    providers: [\n        provideCustomA11yIcon(\n            (service: MyService) => service.iconStrategy,\n            [MyService]\n        ),\n    ],\n})\nexport class MyComponent {}\n```\n\n**On Angular v15+:**\n\n```typescript\nimport { provideCustomA11yIcon } from '@a11y-ngx/icon';\n\n@Component({\n    ...,\n    providers: [\n        provideCustomA11yIcon(() => inject(MyService).iconStrategy),\n    ],\n})\nexport class MyComponent {}\n```\n\n> 💡 Let's assume you have chosen the service approach, and the configured strategy is `'image'` so, when you define any `icon` input string within _that_ component, it will be treated as the image's source path for an `<img>` tag.\n\n**Template:**\n\n```html\n<a11y-icon icon=\"/assets/icons/home.png\"></a11y-icon>\n```\n\n**Will Render As:**\n\n```html\n<a11y-icon aria-hidden=\"true\">\n    <img src=\"/assets/icons/home.png\" alt=\"\" />\n</a11y-icon>\n```\n\n## Real-World Use Case\n\nImagine you are creating a custom `DropdownComponent` to be published as an open-source UI library. You don't know (and shouldn't care) if the developer consuming your library uses Material Icons, FontAwesome, or custom SVG images in their application.\n\nBy using `<a11y-icon>`, your component becomes completely agnostic. The end-user configures their icon strategy once at the root level, and your library automatically adapts to use their preferred icon system.\n\n**Your Dropdown Config:**\n\n```typescript\nimport { Icon, IconGlobalStrategy } from '@a11y-ngx/icon';\n\nexport type MyDropdownItem = {\n    label: string;\n    icon?: Icon;\n    ...;\n};\nexport type MyDropdownConfig = Partial<{\n    iconChevron: Icon;\n    iconStrategy: IconGlobalStrategy;\n    ...,\n}>;\n```\n\n> **NOTE:**\n>\n> - `IconGlobalStrategy`: Includes the use of Components and `'image'`.\n> - `IconCustomStrategy`: Includes also the use of TemplateRefs.\n\n**Your Dropdown Provider:**\n\n> 🛠️ Your library should expose a mechanism (like a configuration object or a provider function), allowing developers to define their preferred icon strategy. Store that config in a global service.\n\n```typescript\nexport function provideMyDropdownConfig(config: MyDropdownConfig): Provider {\n    ...\n}\n```\n\n**Your Dropdown Service:**\n\n```typescript\n@Injectable({ providedIn: 'root' })\nexport class MyDropdownService {\n    readonly config: MyDropdownConfig = {};\n\n    // Save the main config from a provider or a \"forRoot()\" method\n    setConfig(config: MyDropdownConfig): void {\n        Object.assign(this.config, config);\n    }\n}\n```\n\n**Your Dropdown Component:**\n\n```typescript\n@Component({\n    selector: 'my-dropdown',\n    template: `\n        <button type=\"button\" class=\"dropdown-trigger\" (click)=\"...\">\n            {{ label }}\n            <a11y-icon [icon]=\"config.iconChevron\"></a11y-icon>\n        </button>\n\n        <div class=\"dropdown-menu\" [hidden]=\"...\" style=\"--icon-size: 20px;\">\n            <div *ngFor=\"let item of items\" class=\"dropdown-item\">\n                <a11y-icon [icon]=\"item.icon\"></a11y-icon>\n                {{ item.label }}\n            </div>\n        </div>\n    `,\n    providers: [\n        provideCustomA11yIcon(\n            // We consume the icon strategy from the service\n            (service: MyDropdownService) => service.config.iconStrategy,\n            [MyDropdownService]\n        ),\n    ],\n})\nexport class MyDropdownComponent {\n    @Input() label: string = 'Menu';\n    @Input() items: MyDropdownItem[] = [];\n\n    get config(): MyDropdownConfig {\n        return this.service.config;\n    };\n\n    constructor(private service: MyDropdownService) {}\n}\n```\n\n**Consumer's Application (End-User):**\n\nThis particular app uses `MatIcon`, so it should set it to the Dropdown's provider:\n\n```typescript\nimport { MatIcon } from '@angular/material/icon';\nimport { provideMyDropdownConfig } from 'my-dropdown-lib';\n\nexport const appConfig: ApplicationConfig = {\n    ...,\n    providers: [\n        ...,\n        provideMyDropdownConfig({\n            iconStrategy: { component: MatIcon, mainEntry: 'content' },\n            iconChevron: 'expand_more',\n        }),\n    ],\n};\n```\n\nThen uses the dropdown component wherever they need:\n\n```typescript\nimport { MyDropdownItem } from 'my-dropdown-lib';\n\n@Component({ ... })\nexport class PaymentMethodComponent {\n    items: MyDropdownItem[] = [\n        { label: 'Credit Card', icon: 'credit_card' },\n        { label: 'Bank Transfer', icon: 'account_balance' },\n        { label: 'Cryptocurrency', icon: 'currency_bitcoin' },\n    ];\n}\n```\n\n```html\n<my-dropdown [items]=\"items\" label=\"Payment Method\"></my-dropdown>\n```\n\n**Result:**\n\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/icon/src/lib/images/example-real-world-dropdown.jpg)\n\n## Examples\n\n> 💡 **A note on the examples below:**\n> Some of the following snippets might seem a bit trivial or oversimplified for a real-world application (check the [real-world use case](#real-world-use-case)). Their sole purpose is to demonstrate the flexibility of the `<a11y-icon>` API and the wide variety of ways it can ingest and render.\n\n- **Direct Inputs** (Passing values directly to the component):\n  - [Raw HTML Source](#raw-html-source)\n  - [Image Source](#image-source)\n  - [Component Source](#component-source)\n  - [TemplateRef Source](#templateref-source)\n- **String Strategies** (Resolving string values via providers):\n  - [Component Strategy](#component-strategy)\n  - [Image Strategy](#image-strategy)\n  - [Template Strategy](#template-strategy)\n\n### Raw HTML Source\n\nThere are two ways to render plain HTML snippets (like SVG vectors or FontAwesome tags):\n\n1. **As a raw string:** Only works if **there is NO strategy** defined (global or custom). The string will be injected as `innerHTML`.\n2. **Using the HTML object:** The `{ html: '...' }` object explicitly forces the component to render raw HTML, safely bypassing any active strategy.\n\n**Typescript:**\n\n```typescript\nreadonly starIconRegular: IconInputHTML = { html: '<i class=\"fa-regular fa-star\"></i>' };\n```\n\n**Template:**\n\n```html\n<!-- 1. Works only if no strategy is defined -->\n<a11y-icon icon='<i class=\"fa-solid fa-star\"></i>'></a11y-icon>\n<!-- 2. Guaranteed to render raw HTML, bypassing any strategy -->\n<a11y-icon [icon]=\"starIconRegular\"></a11y-icon>\n```\n\n**Will Render As:**\n\n```html\n<a11y-icon aria-hidden=\"true\">\n    <span>\n        <i class=\"fa-solid fa-star\"></i>\n    </span>\n</a11y-icon>\n\n<a11y-icon aria-hidden=\"true\">\n    <span>\n        <i class=\"fa-regular fa-star\"></i>\n    </span>\n</a11y-icon>\n```\n\n**Result:**\n\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/icon/src/lib/images/example-plain-html.jpg)\n\n### Image Source\n\nPass an object containing a `src` property to render a standard `<img>` tag.\n\n> 💡 Always use absolute paths (e.g., starting with `/assets/`) to prevent broken images when the route changes.\n\n**Template:**\n\n```html\n<a11y-icon [icon]=\"{ src: '/assets/icons/star.png' }\"></a11y-icon>\n```\n\n**Will Render As:**\n\n```html\n<a11y-icon aria-hidden=\"true\">\n    <img src=\"/assets/icons/star.png\" alt=\"\" />\n</a11y-icon>\n```\n\n**Result:**\n\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/icon/src/lib/images/example-image.jpg)\n\n### Component Source\n\nPass an Angular component class reference. The library will dynamically instantiate and render it.\n\n> 💡 Check later the [Component with Inputs example](#component-with-inputs) in the strategies section to see the full code of the `AppIconComponent` component.\n\n**Typescript:**\n\n```typescript\nimport { IconInputComponent } from '@a11y-ngx/icon';\nimport { MatIcon } from '@angular/material/icon';\nimport { AppIconComponent } from '../app-icon.component';\n\n@Component({ ... })\nexport class MyComponent {\n    readonly iconMaterial: IconInputComponent = {\n        component: MatIcon,\n        content: 'star', // Content Projection method\n    };\n    readonly iconFontAwesome: IconInputComponent = {\n        component: AppIconComponent,\n        inputs: { iconClass: 'fa-solid fa-star' }, // Input method\n    };\n}\n```\n\n**Template:**\n\n```html\n<a11y-icon [icon]=\"iconMaterial\"></a11y-icon>\n<a11y-icon [icon]=\"iconFontAwesome\"></a11y-icon>\n```\n\n**Will Render As:**\n\n```html\n<a11y-icon aria-hidden=\"true\">\n    <mat-icon ...>star</mat-icon>\n</a11y-icon>\n<a11y-icon aria-hidden=\"true\">\n    <app-icon class=\"fa-solid fa-star\"></app-icon>\n</a11y-icon>\n```\n\n**Result:**\n\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/icon/src/lib/images/example-component.jpg)\n\n### TemplateRef Source\n\nPass an `<ng-template>` reference. This is particularly useful for complex DOM structures that require context from the parent component.\n\n**Typescript:**\n\n```typescript\n@Component({ ... })\nexport class MyComponent {\n    notificationsCount: number = 4;\n}\n```\n\n**Template:**\n\n```html\n<ng-template #notificationIcon>\n    <svg\n        viewBox=\"0 0 24 24\"\n        stroke-width=\"2\"\n        stroke=\"#c21515\"\n        [style.fill]=\"notificationsCount > 0 ? '#c21515' : 'transparent'\">\n        <path d=\"M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z\" />\n    </svg>\n</ng-template>\n...\n<button type=\"button\">\n    Notifications\n    <a11y-icon\n        [icon]=\"notificationIcon\"\n        [label]=\"notificationsCount + ' unread messages'\">\n    </a11y-icon>\n</button>\n```\n\n**Will Render As:**\n\n> 🌟 Because a label was provided, the `aria-hidden` attribute is removed. The component automatically applies `role=\"img\"` and the specified `aria-label` so it can be properly announced by screen readers.\n\n```html\n<a11y-icon role=\"img\" aria-label=\"4 unread messages\">\n    <svg>...</svg>\n</a11y-icon>\n```\n\n**Result:**\n\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/icon/src/lib/images/example-template-ref.jpg)\n\n### Component Strategy\n\nSet an Angular component class reference and its main entry type to the token.\n\nYou can configure the component to use:\n\n- [Content Projection](#component-with-content-projection)\n- [Inputs](#component-with-inputs)\n\n#### Component with Content Projection\n\nFor any icon component that works with content projection, like Material Icons, you have to configure it like this:\n\n**Component:**\n\n```typescript\nproviders: [\n    provideCustomA11yIcon(() => ({\n        component: MatIcon,\n        mainEntry: 'content',\n    })),\n],\n```\n\nNow, when you define the `icon` input string, it will be treated as _content projection_ for that `MatIcon` component.\n\n**Template:**\n\n```html\n<a11y-icon icon=\"star\"></a11y-icon>\n```\n\n**Will Render As:**\n\n```html\n<a11y-icon aria-hidden=\"true\">\n    <mat-icon ...>star</mat-icon>\n</a11y-icon>\n```\n\n#### Component with Inputs\n\nFor any icon component that works with inputs, like the one we are creating next that works with class names (like FontAwesome), you have to configure it like this:\n\n**Your Custom Icon Component:**\n\n```typescript\nimport { Component, Input } from '@angular/core';\n\n@Component({\n    selector: 'app-icon',\n    template: '',\n    host: {\n        // Since FontAwesome is based on 'class names',\n        // we'll apply them to the host\n        '[class]': 'iconClass',\n    },\n})\nexport class AppIconComponent {\n    @Input() iconClass!: string;\n}\n```\n\n**Component:**\n\n```typescript\nproviders: [\n    provideCustomA11yIcon(() => ({\n        component: AppIconComponent,\n        mainEntry: 'input',\n        inputName: 'iconClass',\n    })),\n],\n```\n\nNow, when you define the `icon` input string, it will be treated as the _input_ for the `AppIconComponent` component.\n\n**Template:**\n\n```html\n<a11y-icon icon=\"fa-regular fa-file\"></a11y-icon>\n```\n\n**Will Render As:**\n\n```html\n<a11y-icon aria-hidden=\"true\">\n    <app-icon class=\"fa-regular fa-file\"></app-icon>\n</a11y-icon>\n```\n\n### Image Strategy\n\nThis strategy tells the component to treat any string passed to the `icon` input as an image path/URL.\n\n> 💡 Check also [how to configure the Base Path](#the-base-path).\n\n**Component:**\n\n```typescript\nproviders: [\n    provideCustomA11yIcon(() => 'image'),\n],\n```\n\nNow, when you define the `icon` input string, it will be treated as the image _source_.\n\n**Template:**\n\n```html\n<a11y-icon icon=\"/assets/icon-home.png\"></a11y-icon>\n```\n\n**Will Render As:**\n\n```html\n<a11y-icon aria-hidden=\"true\">\n    <img src=\"/assets/icon-home.png\" alt=\"\">\n</a11y-icon>\n```\n\n### Template Strategy\n\nYou can pass a `TemplateRef` as the default strategy.\n\nBecause `<a11y-icon>` handles the template instantiation, it exposes the original `icon` payload back to the template via the `$implicit` context variable. The consumer must use \"`let-something`\" to access it.\n\n> **IMPORTANT:** Unlike the component or image strategies, a `TemplateRef` cannot be provided directly because it only exists _after_ the HTML is rendered. To use it as a strategy, you must first capture the template instance at runtime (for example, via an `@Input()`, `@ContentChild()` or retrieving it from an injected Service) and _then_ return it through the provider's factory function.\n\n- [Template Strategy via Input](#template-strategy-via-input)\n- [Template Strategy via Content Child](#template-strategy-via-content-child)\n\n#### Template Strategy via Input\n\nFor this example we'll use `<mat-icon>` within the template.\n\n**Custom List Component:**\n\n```typescript\n@Component({\n    selector: 'my-list',\n    template: `\n        <div *ngFor=\"let item of items\">\n            <a11y-icon [icon]=\"item.icon\"></a11y-icon>\n            {{ item.name }}\n        </div>\n    `,\n    providers: [\n        provideCustomA11yIcon(\n            (comp: MyListComponent) => comp.iconTemplate,\n            [forwardRef(() => MyListComponent)]\n        ),\n    ],\n})\nexport class MyListComponent {\n    @Input() iconTemplate: TemplateRef<unknown> | undefined;\n\n    readonly items: Item[] = [\n        { name: 'Contrast', icon: 'contrast' },\n        { name: 'Brightness', icon: 'brightness_6' },\n        ...\n    ];\n}\n```\n\n**Parent Template:**\n\n```html\n<ng-template #matIconTemplate let-icon>\n    <mat-icon>{{ icon }}</mat-icon>\n</ng-template>\n\n<my-list [iconTemplate]=\"matIconTemplate\"></my-list>\n```\n\n**Will Render As:**\n\n```html\n<my-list>\n    <div>\n        <a11y-icon aria-hidden=\"true\">\n            <mat-icon ...>contrast</mat-icon>\n        </a11y-icon>\n        Contrast\n    </div>\n    <div>\n        <a11y-icon aria-hidden=\"true\">\n            <mat-icon ...>brightness_6</mat-icon>\n        </a11y-icon>\n        Brightness\n    </div>\n    ...\n</my-list>\n```\n\n**Result:**\n\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/icon/src/lib/images/example-strategy-template-via-input.jpg)\n\n#### Template Strategy via Content Child\n\nFor this example we'll use FontAwesome within the template.\n\n**Custom List Component:**\n\n```typescript\n@Component({\n    selector: 'my-list',\n    template: `\n        <ng-container *ngIf=\"iconTemplate\">\n            <div *ngFor=\"let item of items\">\n                <a11y-icon [icon]=\"item.icon\"></a11y-icon>\n                {{ item.name }}\n            </div>\n        </ng-container>\n    `,\n    providers: [\n        provideCustomA11yIcon(\n            (comp: MyListComponent) => comp.iconTemplate,\n            [forwardRef(() => MyListComponent)]\n        ),\n    ],\n})\nexport class MyListComponent {\n    @ContentChild(TemplateRef) iconTemplate!: TemplateRef<unknown>;\n\n    readonly items: Item[] = [\n        { name: 'Contrast', icon: 'fa-solid fa-circle-half-stroke' },\n        { name: 'Brightness', icon: 'fa-regular fa-sun' },\n        ...\n    ];\n}\n```\n\n**Parent Template:**\n\n```html\n<my-list>\n    <ng-template let-iconClass>\n        <i [class]=\"iconClass\"></i>\n    </ng-template>\n</my-list>\n```\n\n**Will Render As:**\n\n```html\n<my-list>\n    <div>\n        <a11y-icon aria-hidden=\"true\">\n            <i class=\"fa-solid fa-circle-half-stroke\"></i>\n        </a11y-icon>\n        Contrast\n    </div>\n    <div>\n        <a11y-icon aria-hidden=\"true\">\n            <i class=\"fa-regular fa-sun\"></i>\n        </a11y-icon>\n        Brightness\n    </div>\n    ...\n</my-list>\n```\n\n**Result:**\n\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/icon/src/lib/images/example-strategy-template-via-content-child.jpg)\n","readmeFilename":"README.md"}