ion-icon-angular-standalone

Ionic Angular's standalone IonIcon component requires indivisual icons to be imported and registered to the framework via addIcons.

https://ionicframework.com/docs/angular/build-options#standalone

This library provides a wrapper for IonIcon component for each icon, that does exactly that.

Installation

npm i -S ion-icon-angular-standalone

This library has peer dependencies, notably:

• @angular/core >=17.3.0
• @ionic/angular >=8.1.3
• ionicons >=7.2.3"

(Minimum requirements are intentionally kept low. Please use newer versions of your preference.)

Usage

Per-icon ion-icon components

In your component, import the icon components such as IonIcon_logoIonic from ion-icon-angular-standalone instead of IonIcon from @ionic/angular/standalone:

// instead of:
// import { IonIcon } from '@ionic/angular';
// import { addIcons } from 'ionicons';
// import { logoIonic } from 'ionicons/icons';
import { IonIcon_logoIonic } from 'ion-icon-angular-standalone';

@Component({
  selector: 'foo-bar',
  template: `
    <ion-icon name="logo-ionic"></ion-icon>
  `, // As long as static `name` attribute is used, template stays the same.
  standalone: true,
  imports: [
    IonIcon_logoIonic, // instead of `IonIcon`
  ],
})
export class FooBarComponent {
  // no need to call `addIcons({ logoIonic })`
}

For usage of ion-icon with src attribute, ion-icon-angular-standalone contains IonIconWithoutName component as well.

ion-icon component with branded-type

For ion-icon without static name attribute, you can use the IonIconWithBrandedName component from ion-icon-angular-standalone/branded.

This is useful when you have a component that takes an icon name as its input and renders ion-icon element in its template with that name. Now, you can do so in a type-safe way that prevents you and the component's users from missing addIcons calls.

// instead of:
// import { IonIcon } from '@ionic/angular';
// import { addIcons } from 'ionicons';
import { addIcon, IconName, IonIconWithBrandedName } from 'ion-icon-angular-standalone/branded';
import { logoIonic } from 'ionicons/icons';

@Component({
  selector: 'foo-bar',
  template: `
    <ion-icon [name]="iconName ?? fallbackIconName"></ion-icon>
  `,
  standalone: true,
  imports: [
    IonIconWithBrandedName, // instead of IonIcon
  ],
})
export class FooBarComponent {
  // `IconName` type makes sure the input is `addIcon()`ed already. 
  @Input() iconName: IconName | undefined = undefined;
  
  // Instead of plain string, use the return value of `addIcon` function.
  readonly fallbackIconName = addIcon({ logoIonic }); // 'logo-ionic' as IconName
}

Restricting regular IonIcon

It is hightly recommended to restrict imports of IonIcon from @ionic/angular/standalone in your codebase.

ESLint

{
  "no-restricted-imports": [
    "error",
    {
      "paths": [
        {
          "name": "@ionic/angular",
          "message": "Use @ionic/angular/standalone instead."
        },
        {
          "name": "@ionic/angular/standalone",
          "importNames": ["IonIcon"],
          "message": "Use components from ion-icon-angular-standalone instead."
        }
      ]
    }
  ]
}