ion-icon-angular-standalone

Simplify IonIcon usage in standalone Ionic Angular applications

Overview

Ionic Angular's standalone IonIcon component requires individual icons to be imported and registered via addIcons.
https://ionicframework.com/docs/angular/build-options#standalone

This library eliminates that manual work by providing pre-configured wrapper components for each icon.

Key improvements:
- No manual registration - Icons auto-register when loaded
- Better tree-shaking - Only bundle icons you actually use
- Type safety - Catch missing icons at compile-time, not runtime
- Simpler workflow - Just import the icon component you need

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

$3

Standard Ionic usage:

`typescript
// 🔧 Standard Ionic usage
import { IonIcon } from '@ionic/angular/standalone';
import { addIcons } from 'ionicons';
import { logoIonic } from 'ionicons/icons';

@Component({
template: ,
standalone: true,
imports: [IonIcon]
})
export class MyComponent {
constructor() {
addIcons({ logoIonic }); // Manual registration required
}
}
`

With this library:

`typescript
// ✅ With ion-icon-angular-standalone
import { IonIcon_logoIonic } from 'ion-icon-angular-standalone';

@Component({
template: ,
standalone: true,
imports: [IonIcon_logoIonic] // Icon auto-registers itself!
})
export class MyComponent {
// No addIcons() call needed - it's handled automatically!
}
`

Key Benefits:
- Zero configuration: No addIcons() calls needed
- Bundle optimization: Only icons you import are included
- Simple workflow: Just import the specific icon component
- No runtime errors: Missing icons caught at build time

Note: For ion-icon with src attribute, use the IonIconWithoutName component.

$3

For components that accept dynamic icon names via inputs or properties, you can use ion-icon-angular-standalone/branded.

Standard Ionic usage:

`typescript
// 🔧 Standard Ionic usage
import { IonIcon } from '@ionic/angular/standalone';
import { addIcons } from 'ionicons';
import { logoIonic } from 'ionicons/icons';

@Component({
selector: 'my-icon',
template: ,
standalone: true,
imports: [IonIcon]
})
export class MyIconComponent {
@Input() iconName: string | undefined = undefined; // No type safety!
// ⚠️ ANY icon passed to iconName must be registered elsewhere with addIcons()
// or it will result in runtime errors (blank icons)

readonly fallbackIconName = 'logo-ionic';

constructor() {
addIcons({ logoIonic }); // Manual registration required, but only fallback icon registered here!
}
}
`

With this library:

`typescript
// ✅ With ion-icon-angular-standalone/branded
import { addIcon, IconName, IonIconWithBrandedName } from 'ion-icon-angular-standalone/branded';
import { logoIonic } from 'ionicons/icons';

@Component({
selector: 'my-icon',
template: ,
standalone: true,
imports: [IonIconWithBrandedName]
})
export class MyIconComponent {
@Input() iconName: IconName | undefined = undefined; // Compile-time safety!
// ✅ IconName type ensures ANY icon passed to iconName is already registered!
// No runtime errors possible - unregistered icons caught at compile-time

readonly fallbackIconName = addIcon({ logoIonic }); // Registers the icon and returns IconName
}
`

Key Benefits:
- Compile-time safety: IconName type prevents unregistered icons
- Explicit registration: Each addIcon() call is clear and purposeful
- Runtime error prevention: No more blank icons from missing registrations

Important Note: Components from ion-icon-angular-standalone (e.g. IonIcon_logoIonic) and ion-icon-angular-standalone/branded (i.e. IonIconWithBrandedName) have overlapping selectors and cannot coexist in the same component's imports array. Choose one method per component.

Enforcing Consistent Usage

Highly recommended: Use ESLint to prevent standard IonIcon imports and ensure consistent usage across your codebase:

Add this rule to your .eslintrc.json:

`json
{
"rules": {
"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."
}
]
}
]
}
}
`

This prevents developers from accidentally using the standard IonIcon` and ensures consistent icon usage patterns across your entire codebase.

Articles

- New library for easier IonIcon usage in Ionic Angular standalone - Medium article introducing the library
- Standalone時代のIonic Angularでion-iconをスマートに扱う！ 〜ion-icon-angular-standaloneのご紹介〜 - The same article in Japanese on Zenn

Contributing

Contributions are welcome! Please check the GitHub repository for more information.