ngx-tabler-icons/README.md

Tabler Icons library for Angular applications

# ngx-tabler-icons

Angular library for using [Tabler Icons](https://tabler-icons.io/) through the standalone `i-tabler-icon` component.

## Compatibility

| Angular | ngx-tabler-icons |
| --- | --- |
| 22 | 22.x |
| 20 - 21 | 3.0.x |

Versions 3.0.x and 22.x use the same standalone consumer API. Starting with version 22, the library's major version tracks the supported Angular major version.

## Install

```bash
npm install ngx-tabler-icons@22
```

## Standalone setup

Register only the icons your application uses in `app.config.ts`:

```ts
import { provideZoneChangeDetection } from '@angular/core';
import type { ApplicationConfig } from '@angular/core';
import { provideIcons } from 'ngx-tabler-icons';
import { IconHeartFilled, IconHome, IconUser } from 'ngx-tabler-icons/icons';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection(),
    provideIcons({
      IconHome,
      IconUser,
      IconHeartFilled,
    }),
  ],
};
```

Bootstrap the standalone root component with that configuration:

```ts
import { bootstrapApplication } from '@angular/platform-browser';

import { appConfig } from './app/app.config';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, appConfig)
  .catch((error: unknown) => console.error(error));
```

`@angular/platform-browser-dynamic` and `platformBrowserDynamic` are not required for this setup.

Import `ITablerIcon` in every standalone component that uses the icon component:

```ts
import { Component } from '@angular/core';
import { ITablerIcon } from 'ngx-tabler-icons';

@Component({
  selector: 'app-example',
  imports: [ITablerIcon],
  template: `
    <i-tabler-icon name="home" />
    <i-tabler-icon name="user" [size]="20" />
    <i-tabler-icon name="heart-filled" [size]="22" />
  `,
})
export class ExampleComponent {}
```

An icon must be included in `provideIcons` before it can be rendered. This keeps unused icon SVGs out of the application bundle.

## Inputs

| Input | Type | Default | Notes |
| --- | --- | --- | --- |
| `name` | `IconName` | Required | Kebab-case icon name, such as `home` or `heart-filled`. |
| `size` | `number` | `24` | Width and height in pixels. |
| `strokeWidth` | `number` | `1.5` | Forced to `0` for icons whose name ends in `-filled`. |

## Typed icon names

The main entry point exports:

- `ITablerIcon`: standalone icon component.
- `provideIcons`: application-level icon registry provider.
- `IconName`: union of all generated icon names.
- `IconNameFromRegistry<T>`: names derived from a specific icon registry.
- `IconDefinition` and `IconRegistry`: registry-related types.

Icon constants are exposed separately through `ngx-tabler-icons/icons`.

```ts
import type { IconNameFromRegistry } from 'ngx-tabler-icons';
import { IconHome, IconUser } from 'ngx-tabler-icons/icons';

const appIcons = {
  IconHome,
  IconUser,
} as const;

type AppIconName = IconNameFromRegistry<typeof appIcons>; // 'home' | 'user'
```

## NgModule applications

The library component is standalone, but it can still be imported by an NgModule application:

```ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { ITablerIcon, provideIcons } from 'ngx-tabler-icons';
import { IconHome } from 'ngx-tabler-icons/icons';

@NgModule({
  imports: [BrowserModule, ITablerIcon],
  providers: [provideIcons({ IconHome })],
})
export class AppModule {}
```

## Upgrading from 3.0.x to 22.x

Version 22 keeps the public API introduced in 3.0.0 and retained in 3.0.1. Existing imports and templates continue to use:

- `provideIcons` from `ngx-tabler-icons`.
- `ITablerIcon` from `ngx-tabler-icons`.
- Icon constants from `ngx-tabler-icons/icons`.
- `<i-tabler-icon name="..." />` in templates.

No consumer API migration is required. The major version change indicates that version 22 requires Angular 22, while version 3.0.x supports Angular 20 and 21.

```bash
npm install ngx-tabler-icons@22
```

## Migrating from 1.x or 2.x

Versions 1.x and 2.x used generated components and modules. To migrate to the registry-based API available since 3.0.0:

1. Remove generated icon modules and components such as `ITabler2faModule` and `<i-tabler-2fa>`.
2. Import the required SVG constants from `ngx-tabler-icons/icons`.
3. Register those constants once with `provideIcons` in `app.config.ts` or the root NgModule.
4. Import the standalone `ITablerIcon` component where it is used.
5. Replace generated selectors with `<i-tabler-icon name="..." />`.

For example:

```html
<!-- 1.x and 2.x -->
<i-tabler-home></i-tabler-home>

<!-- 3.0.x and later -->
<i-tabler-icon name="home" />
```

## Development

Install dependencies with pnpm and use the project-specific commands:

```bash
pnpm install
pnpm build:lib
pnpm build:app
pnpm run pack
```

- `pnpm build` and `pnpm build:lib` build only the publishable `ngx-tabler-icons` library.
- `pnpm build:app` builds the local demo application. Because the demo consumes the packaged library, build the library first after a clean checkout.
- `pnpm run pack` builds the library and creates `dist/ngx-tabler-icons-22.0.0.tgz` for local installation testing before publishing.
- `pnpm watch` watches the library.
- `pnpm watch:app` watches the demo application.
- `pnpm start` serves the demo application.

The primary public API is maintained in `projects/ngx-tabler-icons/src/public-api.ts`. The `ngx-tabler-icons/icons` directory is a secondary package entry point.

Install the generated tarball from a consuming project using its relative or absolute path:

```bash
pnpm add ../ngx-tabler-icons/dist/ngx-tabler-icons-22.0.0.tgz
```

Use `pnpm run pack` rather than `pnpm pack`: the explicit `run` ensures that pnpm executes this repository's script, including the production library build.

## Updating generated icons

Generate icon constants from the upstream `tabler/tabler-icons` repository with:

```bash
pnpm generate:icons
```

The generator reads the upstream `icons/outline` and `icons/filled` directories and writes:

- `projects/ngx-tabler-icons/icons/svg/*`
- `projects/ngx-tabler-icons/icons/index.ts`
- `projects/ngx-tabler-icons/src/lib/icon-names.generated.ts`

The public API file is maintained manually and is not replaced by the generator.

The upstream repository and ref can be configured with:

- `TABLER_ICONS_REF` (default: `main`)
- `TABLER_ICONS_OWNER` (default: `tabler`)
- `TABLER_ICONS_REPO` (default: `tabler-icons`)

Example:

```bash
TABLER_ICONS_REF=v3.37.1 pnpm generate:icons
```

## Contributing

Pull requests and issues are welcome.