Ng Icons (ng-icons/ng-icons)

Ng Icons

https://github.com/ng-icons/ng-icons
Admin
Ng Icons is an all-in-one Angular icon library that provides access to over 100,000 icons from 30+...

Tokens:61,986
Snippets:688
Trust Score:4.7
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# Ng Icons

Ng Icons is a comprehensive all-in-one icon library for Angular applications that provides unified access to over 100,000 icons from 30+ popular icon sets through a single, consistent component API. It supports both traditional NgModule-based applications and modern standalone components, with features including tree-shaking for optimal bundle sizes, dynamic icon loading, icon stacking, and experimental variable font support via Material Symbols.

The library is designed for modern Angular applications (version 11+) and provides a seamless developer experience by allowing icons from different icon sets like Heroicons, Bootstrap Icons, Font Awesome, Material Icons, Feather Icons, and many others to be used interchangeably with the same `<ng-icon>` component. Icons are imported as TypeScript constants containing SVG strings, enabling full tree-shaking to include only the icons actually used in your application.

## Installation

Install the core package and any icon set packages you need.

```bash
# Using npm
npm install @ng-icons/core @ng-icons/heroicons @ng-icons/feather-icons @ng-icons/bootstrap-icons

# Using yarn
yarn add @ng-icons/core @ng-icons/heroicons @ng-icons/feather-icons @ng-icons/bootstrap-icons

# Using pnpm
pnpm add @ng-icons/core @ng-icons/heroicons @ng-icons/feather-icons @ng-icons/bootstrap-icons
```

## NgIconsModule.withIcons() - NgModule-based Setup

Register icons in your Angular module using the `NgIconsModule.withIcons()` method. This approach works with traditional NgModule-based applications and supports lazy loading icons in child modules.

```typescript
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { NgIconsModule } from '@ng-icons/core';
import { featherAirplay, featherHeart, featherSettings } from '@ng-icons/feather-icons';
import { heroUsers, heroHome, heroCog6Tooth } from '@ng-icons/heroicons/outline';
import { heroUserSolid } from '@ng-icons/heroicons/solid';
import { bootstrapGithub, bootstrapTwitter } from '@ng-icons/bootstrap-icons';

@NgModule({
  imports: [
    BrowserModule,
    NgIconsModule.withIcons({
      featherAirplay,
      featherHeart,
      featherSettings,
      heroUsers,
      heroHome,
      heroCog6Tooth,
      heroUserSolid,
      bootstrapGithub,
      bootstrapTwitter
    })
  ],
  declarations: [AppComponent],
  bootstrap: [AppComponent]
})
export class AppModule {}
```

## NgIcon Component - Basic Usage

The `<ng-icon>` component renders icons by name. Use the `name` input to specify which registered icon to display, and customize appearance with `size`, `color`, and `strokeWidth` inputs.

```html
<!-- Basic icon usage -->
<ng-icon name="featherHeart"></ng-icon>

<!-- Icon with custom size (accepts CSS values) -->
<ng-icon name="heroUsers" size="24px"></ng-icon>
<ng-icon name="heroHome" size="2rem"></ng-icon>
<ng-icon name="heroCog6Tooth" size="1.5em"></ng-icon>

<!-- Icon with custom color -->
<ng-icon name="featherHeart" color="red"></ng-icon>
<ng-icon name="bootstrapGithub" color="#333"></ng-icon>
<ng-icon name="bootstrapTwitter" color="var(--primary-color)"></ng-icon>

<!-- Icon with custom stroke width (for stroke-based iconsets like Heroicons outline) -->
<ng-icon name="heroUsers" strokeWidth="2"></ng-icon>
<ng-icon name="heroHome" strokeWidth="1"></ng-icon>

<!-- Combining multiple customizations -->
<ng-icon name="featherSettings" size="32px" color="blue" strokeWidth="1.5"></ng-icon>

<!-- Using icons in buttons -->
<button>
  <ng-icon name="heroUserSolid" size="16px"></ng-icon>
  Profile
</button>
```

## provideIcons() - Standalone Component Setup

For standalone components, use `provideIcons()` in the component's providers array. Import `NgIcon` directly in the component's imports. This approach enables better tree-shaking and component-level icon scoping.

```typescript
import { Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { featherAirplay, featherCamera, featherMusic } from '@ng-icons/feather-icons';
import { heroUsers, heroPhoto, heroMusicalNote } from '@ng-icons/heroicons/outline';

@Component({
  selector: 'app-media-player',
  standalone: true,
  imports: [NgIcon],
  providers: [provideIcons({ featherAirplay, featherCamera, featherMusic, heroUsers, heroPhoto, heroMusicalNote })],
  template: `
    <div class="player-controls">
      <button><ng-icon name="featherAirplay" size="20px"></ng-icon></button>
      <button><ng-icon name="featherCamera" size="20px"></ng-icon></button>
      <button><ng-icon name="featherMusic" size="20px"></ng-icon></button>
    </div>

    <div class="user-section">
      <ng-icon name="heroUsers" size="24px" color="#6366f1"></ng-icon>
      <ng-icon name="heroPhoto" size="24px" color="#6366f1"></ng-icon>
      <ng-icon name="heroMusicalNote" size="24px" color="#6366f1"></ng-icon>
    </div>
  `
})
export class MediaPlayerComponent {}
```

## Direct SVG Input

Pass SVG strings directly to the `<ng-icon>` component using the `svg` input. This is useful when receiving icons as props or when dynamically generating SVG content without pre-registering icons.

```typescript
import { Component, Input } from '@angular/core';
import { NgIcon } from '@ng-icons/core';
import { featherHeart, featherStar, featherBookmark } from '@ng-icons/feather-icons';

// Parent component passing icon as data
@Component({
  selector: 'app-rating',
  standalone: true,
  imports: [IconButtonComponent],
  template: `
    <app-icon-button [icon]="heartIcon" label="Like"></app-icon-button>
    <app-icon-button [icon]="starIcon" label="Favorite"></app-icon-button>
    <app-icon-button [icon]="bookmarkIcon" label="Save"></app-icon-button>
  `
})
export class RatingComponent {
  heartIcon = featherHeart;
  starIcon = featherStar;
  bookmarkIcon = featherBookmark;
}

// Child component receiving icon via input
@Component({
  selector: 'app-icon-button',
  standalone: true,
  imports: [NgIcon],
  template: `
    <button class="icon-btn">
      <ng-icon [svg]="icon" size="18px"></ng-icon>
      <span>{{ label }}</span>
    </button>
  `
})
export class IconButtonComponent {
  @Input({ required: true }) icon!: string;
  @Input() label: string = '';
}
```

## provideNgIconsConfig() - Global Configuration

Configure default icon settings application-wide using `provideNgIconsConfig()`. This sets default values for size, color, and stroke width that apply to all icons unless overridden at the component level.

```typescript
import { bootstrapApplication } from '@angular/platform-browser';
import { provideNgIconsConfig } from '@ng-icons/core';
import { AppComponent } from './app/app.component';

// Standalone application bootstrap
bootstrapApplication(AppComponent, {
  providers: [
    provideNgIconsConfig({
      size: '1.5em',           // Default size for all icons
      color: 'currentColor',    // Default color (inherits text color)
      strokeWidth: 1.5          // Default stroke width for stroke-based icons
    })
  ]
});

// NgModule-based application
import { NgModule } from '@angular/core';
import { NgIconsModule, provideNgIconsConfig } from '@ng-icons/core';
import { featherCheck, featherX } from '@ng-icons/feather-icons';

@NgModule({
  imports: [
    NgIconsModule.withIcons({ featherCheck, featherX })
  ],
  providers: [
    provideNgIconsConfig({
      size: '24px',
      color: '#374151'
    })
  ]
})
export class AppModule {}
```

## withContentSecurityPolicy() - CSP Compliance

Enable Content Security Policy compliance when your application has strict CSP rules. This feature processes SVG content to avoid inline style violations by converting style attributes to data attributes and applying them programmatically.

```typescript
import { bootstrapApplication } from '@angular/platform-browser';
import { provideNgIconsConfig, withContentSecurityPolicy } from '@ng-icons/core';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    provideNgIconsConfig(
      {
        size: '1.5em',
        color: 'currentColor'
      },
      withContentSecurityPolicy()  // Enable CSP-safe SVG processing
    )
  ]
});

// Using with NgModule
import { NgModule } from '@angular/core';
import { NgIconsModule, provideNgIconsConfig, withContentSecurityPolicy } from '@ng-icons/core';
import { heroShieldCheck, heroLockClosed } from '@ng-icons/heroicons/outline';

@NgModule({
  imports: [
    NgIconsModule.withIcons({ heroShieldCheck, heroLockClosed })
  ],
  providers: [
    provideNgIconsConfig({}, withContentSecurityPolicy())
  ]
})
export class SecureAppModule {}
```

## withExceptionLogger() - Strict Error Handling

Enable strict error handling that throws exceptions when attempting to use unregistered icons. By default, Ng Icons logs warnings to the console; this feature converts warnings to thrown errors for stricter development and testing.

```typescript
import { bootstrapApplication } from '@angular/platform-browser';
import { provideNgIconsConfig, withExceptionLogger } from '@ng-icons/core';
import { AppComponent } from './app/app.component';

// Development configuration with strict error handling
bootstrapApplication(AppComponent, {
  providers: [
    provideNgIconsConfig(
      { size: '1.5em' },
      withExceptionLogger()  // Throws errors instead of console warnings
    )
  ]
});

// Combining multiple features
import { provideNgIconsConfig, withContentSecurityPolicy, withExceptionLogger } from '@ng-icons/core';

bootstrapApplication(AppComponent, {
  providers: [
    provideNgIconsConfig(
      { size: '24px', color: '#1f2937' },
      withContentSecurityPolicy(),
      withExceptionLogger()
    )
  ]
});
```

## provideNgIconLoader() - Dynamic Icon Loading

Load icons dynamically at runtime using a custom loader function. The loader receives the icon name and can return a `Promise<string>`, `Observable<string>`, or `string` containing the SVG content. This is ideal for loading icons from a server or generating them programmatically.

```typescript
import { bootstrapApplication } from '@angular/platform-browser';
import { inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { provideHttpClient } from '@angular/common/http';
import { provideNgIconLoader, withCaching } from '@ng-icons/core';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(),

    // Basic loader - fetches SVGs from assets folder
    provideNgIconLoader(name => {
      const http = inject(HttpClient);
      return http.get(`/assets/icons/${name}.svg`, { responseType: 'text' });
    }),
  ]
});

// Loader with caching to prevent duplicate requests
bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(),

    provideNgIconLoader(
      name => {
        const http = inject(HttpClient);
        return http.get(`/assets/icons/${name}.svg`, { responseType: 'text' });
      },
      withCaching()  // Cache loaded icons to avoid repeated HTTP requests
    ),
  ]
});

// Advanced loader with error handling and fallback
provideNgIconLoader(async name => {
  const http = inject(HttpClient);
  try {
    return await http.get(`/api/icons/${name}`, { responseType: 'text' }).toPromise();
  } catch (error) {
    console.warn(`Icon "${name}" not found, using fallback`);
    return '<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" fill="none" stroke="currentColor"/></svg>';
  }
}, withCaching());
```

## NgIconStack Component - Layered Icons

Stack multiple icons on top of each other to create composite icons. The `ng-icon-stack` component requires a size and positions child icons in layers. Individual icons within the stack can have their own size overrides.

```typescript
import { Component } from '@angular/core';
import { NgIcon, NgIconStack, provideIcons } from '@ng-icons/core';
import { faCircle, faFlag, faBan, faExclamation, faHeart, faPlus } from '@ng-icons/font-awesome/solid';

@Component({
  selector: 'app-stacked-icons',
  standalone: true,
  imports: [NgIcon, NgIconStack],
  providers: [provideIcons({ faCircle, faFlag, faBan, faExclamation, faHeart, faPlus })],
  template: `
    <!-- Flag on circle background -->
    <ng-icon-stack size="32px">
      <ng-icon name="faCircle" color="#3b82f6"></ng-icon>
      <ng-icon name="faFlag" size="16px" color="white"></ng-icon>
    </ng-icon-stack>

    <!-- Ban/prohibited icon overlay -->
    <ng-icon-stack size="40px">
      <ng-icon name="faHeart" color="#ef4444"></ng-icon>
      <ng-icon name="faBan" size="40px" color="rgba(0,0,0,0.5)"></ng-icon>
    </ng-icon-stack>

    <!-- Warning/alert icon -->
    <ng-icon-stack size="36px">
      <ng-icon name="faCircle" color="#f59e0b"></ng-icon>
      <ng-icon name="faExclamation" size="20px" color="white"></ng-icon>
    </ng-icon-stack>

    <!-- Add/plus button -->
    <ng-icon-stack size="28px">
      <ng-icon name="faCircle" color="#10b981"></ng-icon>
      <ng-icon name="faPlus" size="14px" color="white"></ng-icon>
    </ng-icon-stack>
  `
})
export class StackedIconsComponent {}
```

## provideNgGlyphs() - Variable Icon Fonts (Experimental)

Enable variable icon fonts support, currently available for Material Symbols. Unlike SVG icons, variable fonts require loading the font stylesheet separately. This feature provides access to adjustable weight, grade, optical size, and fill properties.

```typescript
import { bootstrapApplication } from '@angular/platform-browser';
import { provideNgGlyphs, provideNgGlyphsConfig } from '@ng-icons/core';
import { withMaterialSymbolsOutlined, withMaterialSymbolsRounded } from '@ng-icons/material-symbols';
import { AppComponent } from './app/app.component';

// Add to index.html: <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined" rel="stylesheet" />

bootstrapApplication(AppComponent, {
  providers: [
    // Register glyphsets - first one becomes the default
    provideNgGlyphs(
      withMaterialSymbolsOutlined(),
      withMaterialSymbolsRounded()
    ),

    // Optional: configure default glyph settings
    provideNgGlyphsConfig({
      size: 24,
      weight: 400,
      grade: 0,
      fill: false,
      opticalSize: 24
    })
  ]
});
```

## NgGlyph Component - Variable Font Icons

Use the `<ng-glyph>` component to render variable font icons with full control over font variation settings. Supports weight, grade, optical size, fill, and standard size/color customizations.

```typescript
import { Component } from '@angular/core';
import { NgGlyph } from '@ng-icons/core';

@Component({
  selector: 'app-glyph-demo',
  standalone: true,
  imports: [NgGlyph],
  template: `
    <!-- Basic glyph usage -->
    <ng-glyph name="settings"></ng-glyph>
    <ng-glyph name="home"></ng-glyph>
    <ng-glyph name="favorite"></ng-glyph>

    <!-- Customized size and color -->
    <ng-glyph name="search" size="32px" color="#6366f1"></ng-glyph>
    <ng-glyph name="notifications" size="28" color="var(--accent-color)"></ng-glyph>

    <!-- Variable font properties -->
    <ng-glyph name="favorite" [fill]="true" color="#ef4444"></ng-glyph>
    <ng-glyph name="star" [fill]="true" [weight]="700" color="#f59e0b"></ng-glyph>

    <!-- Adjusting weight (100-700) -->
    <ng-glyph name="home" [weight]="200"></ng-glyph>
    <ng-glyph name="home" [weight]="400"></ng-glyph>
    <ng-glyph name="home" [weight]="700"></ng-glyph>

    <!-- Optical size for different display contexts -->
    <ng-glyph name="settings" [opticalSize]="20" size="20px"></ng-glyph>
    <ng-glyph name="settings" [opticalSize]="48" size="48px"></ng-glyph>

    <!-- Grade adjustment (-25 to 200) -->
    <ng-glyph name="thumb_up" [grade]="-25"></ng-glyph>
    <ng-glyph name="thumb_up" [grade]="0"></ng-glyph>
    <ng-glyph name="thumb_up" [grade]="200"></ng-glyph>

    <!-- Using different glyphsets -->
    <ng-glyph name="settings" glyphset="outlined"></ng-glyph>
    <ng-glyph name="settings" glyphset="rounded"></ng-glyph>

    <!-- Combining all properties -->
    <ng-glyph
      name="favorite"
      size="40px"
      color="#ec4899"
      [fill]="true"
      [weight]="600"
      [grade]="100"
      [opticalSize]="40">
    </ng-glyph>
  `
})
export class GlyphDemoComponent {}
```

## Icon Set Import Patterns

Different icon sets organize icons by variants (outline, solid, etc.). Import from the appropriate subpath based on the icon style you need.

```typescript
// Heroicons - organized by variant
import { heroUsers, heroHome, heroCog6Tooth } from '@ng-icons/heroicons/outline';
import { heroUsersSolid, heroHomeSolid } from '@ng-icons/heroicons/solid';
import { heroUsersMini, heroHomeMini } from '@ng-icons/heroicons/mini';
import { heroUsersMicro } from '@ng-icons/heroicons/micro';

// Material Icons - organized by variant
import { matHome, matSettings } from '@ng-icons/material-icons/baseline';
import { matHomeOutline, matSettingsOutline } from '@ng-icons/material-icons/outline';
import { matHomeRound, matSettingsRound } from '@ng-icons/material-icons/round';
import { matHomeSharp, matSettingsSharp } from '@ng-icons/material-icons/sharp';

// Font Awesome - organized by style
import { faCoffee, faHeart, faUser } from '@ng-icons/font-awesome/solid';
import { faHeart as faHeartRegular } from '@ng-icons/font-awesome/regular';
import { faGithub, faTwitter } from '@ng-icons/font-awesome/brands';

// Phosphor Icons - organized by weight
import { phosphorHeart } from '@ng-icons/phosphor-icons/regular';
import { phosphorHeartBold } from '@ng-icons/phosphor-icons/bold';
import { phosphorHeartLight } from '@ng-icons/phosphor-icons/light';
import { phosphorHeartThin } from '@ng-icons/phosphor-icons/thin';
import { phosphorHeartFill } from '@ng-icons/phosphor-icons/fill';
import { phosphorHeartDuotone } from '@ng-icons/phosphor-icons/duotone';

// Single-variant icon sets - import directly
import { featherHeart, featherHome } from '@ng-icons/feather-icons';
import { bootstrapHeart, bootstrapHouse } from '@ng-icons/bootstrap-icons';
import { lucideHeart, lucideHome } from '@ng-icons/lucide';
import { tablerHeart, tablerHome } from '@ng-icons/tabler-icons';
import { ionHeart, ionHome } from '@ng-icons/ionicons';
import { radixHeart } from '@ng-icons/radix-icons';
import { simpleGithub, simpleTwitter } from '@ng-icons/simple-icons';

// Specialty icon sets
import { cryptoBtc, cryptoEth } from '@ng-icons/cryptocurrency-icons';
import { flagUs, flagGb, flagFr } from '@ng-icons/flag-icons';
import { gameChessPawn, gameDice } from '@ng-icons/game-icons';
import { deviconAngular, deviconTypescript } from '@ng-icons/devicon/original';
```

## Complete Application Example

A comprehensive example showing multiple Ng Icons features working together in a real application.

```typescript
import { Component } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { provideHttpClient, HttpClient } from '@angular/common/http';
import { inject } from '@angular/core';
import {
  NgIcon,
  NgIconStack,
  provideIcons,
  provideNgIconsConfig,
  provideNgIconLoader,
  withCaching,
  withContentSecurityPolicy,
  withExceptionLogger
} from '@ng-icons/core';
import { heroHome, heroUsers, heroCog6Tooth, heroBell } from '@ng-icons/heroicons/outline';
import { heroHomeSolid } from '@ng-icons/heroicons/solid';
import { featherHeart, featherShare, featherBookmark } from '@ng-icons/feather-icons';
import { faCircle, faCheck } from '@ng-icons/font-awesome/solid';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [NgIcon, NgIconStack],
  providers: [
    provideIcons({
      heroHome, heroUsers, heroCog6Tooth, heroBell, heroHomeSolid,
      featherHeart, featherShare, featherBookmark,
      faCircle, faCheck
    })
  ],
  template: `
    <nav class="navbar">
      <a href="#" class="nav-link">
        <ng-icon name="heroHome" size="20px"></ng-icon>
        Home
      </a>
      <a href="#" class="nav-link">
        <ng-icon name="heroUsers" size="20px"></ng-icon>
        Users
      </a>
      <a href="#" class="nav-link">
        <ng-icon name="heroCog6Tooth" size="20px"></ng-icon>
        Settings
      </a>
      <button class="notification-btn">
        <ng-icon-stack size="24px">
          <ng-icon name="heroBell"></ng-icon>
          <ng-icon name="faCircle" size="10px" color="#ef4444"
                   style="position: absolute; top: 0; right: 0;"></ng-icon>
        </ng-icon-stack>
      </button>
    </nav>

    <main class="content">
      <article class="card">
        <h2>Article Title</h2>
        <p>Article content goes here...</p>
        <div class="actions">
          <button class="action-btn">
            <ng-icon name="featherHeart" size="18px" color="#ef4444"></ng-icon>
            Like
          </button>
          <button class="action-btn">
            <ng-icon name="featherShare" size="18px"></ng-icon>
            Share
          </button>
          <button class="action-btn">
            <ng-icon name="featherBookmark" size="18px"></ng-icon>
            Save
          </button>
        </div>
      </article>

      <div class="status-indicator">
        <ng-icon-stack size="28px">
          <ng-icon name="faCircle" color="#10b981"></ng-icon>
          <ng-icon name="faCheck" size="14px" color="white"></ng-icon>
        </ng-icon-stack>
        <span>All systems operational</span>
      </div>
    </main>
  `
})
export class AppComponent {}

// Bootstrap with full configuration
bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(),

    // Global icon configuration
    provideNgIconsConfig(
      {
        size: '1.25em',
        color: 'currentColor'
      },
      withContentSecurityPolicy(),
      withExceptionLogger()
    ),

    // Dynamic loader for custom icons
    provideNgIconLoader(
      name => {
        const http = inject(HttpClient);
        return http.get(`/assets/custom-icons/${name}.svg`, { responseType: 'text' });
      },
      withCaching()
    )
  ]
});
```

## Summary

Ng Icons is ideal for Angular applications that need to use icons from multiple icon libraries without managing separate dependencies and inconsistent APIs for each. The library excels in scenarios where bundle size optimization is critical, as its tree-shaking support ensures only the icons actually imported are included in the final bundle. It's particularly well-suited for design systems and component libraries where consistent icon styling and easy switching between icon sets is valuable.

Integration follows Angular's standard patterns - use `NgIconsModule.withIcons()` for NgModule-based apps or `provideIcons()` for standalone components. Icons are consumed through the unified `<ng-icon>` component with consistent inputs for size, color, and stroke width across all icon sets. For applications with strict security requirements, the CSP compliance feature ensures icons render safely. The dynamic loader pattern enables advanced use cases like server-side icon management or lazy-loading icons on demand, while the experimental variable font support via `<ng-glyph>` provides access to Material Symbols' adjustable icon properties.