# Migrating from `lucide-angular` ⇒ `@lucide/angular`

## What changed

`@lucide/angular` moves from a module + single component based API to a more modern Angular approach:

- The library defines modern signal-based, standalone components, without zone.js based change detection.
- Icons are consumed as standalone imports (one component per icon).
- Dynamic icon registration is done via `provideLucideIcons()`, not using `NgModule`.
- Static icons use per-icon components for better tree-shaking.
- Dynamic icons still use a single dynamic component (`svg[lucideIcon]`).
- Global defaults are configured via `provideLucideConfig()`.
- Brand icons have been removed, see the next section.

---

## Step 1 – Update dependencies

Remove `lucide-angular`, and add `@lucide/angular`, see:\
[Getting Started # Installation](/guide/angular/getting-started.md#installation)

---

## Step 2 – Replace `LucideAngularModule.pick(...)` with `provideLucideIcons(...)`

> Notes:
> - Old imports like `AirVentIcon` / `AlarmClock` from `lucide-angular` should be replaced with the new per-icon exports `LucideAirVent` and `LucideAlarmClock`.
> - If you mostly used static icons, you may not need to provide them **at all**, please refer to Step 3.

### Before

#### NgModule based
```ts
import { BrowserModule, NgModule } from '@angular/core';
import { LucideAngularModule, AirVent, AlarmClock } from 'lucide-angular';

@NgModule({
  imports: [
    BrowserModule,
    LucideAngularModule.pick({ AirVent, AlarmClock }),
  ],
})
export class AppModule {}
```

#### Standalone

```ts
import { ApplicationConfig } from '@angular/core';
import { LucideAngularModule, AirVent, AlarmClock } from 'lucide-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    // ...
    importProvidersFrom(LucideAngularModule.pick({ AirVent, AlarmClock })),
  ]
};
```

### After
```ts
import { ApplicationConfig } from '@angular/core';
import { provideLucideIcons, LucideAirVent, LucideAlarmClock } from '@lucide/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    // ...
    provideLucideIcons(
      LucideAirVent,
      LucideAlarmClock,
    ),
  ]
};
```

---

## Step 3 – Replace `<lucide-angular>` / `<lucide-icon>` / `<i-lucide>` / `<span-lucide>`

The legacy package rendered everything through a single component. All of these selectors must be migrated to `<svg>` usage.

### A. Static icons by name

If the icon is known at build time, just use a static import:

#### Before
```html
<lucide-angular name="circle-check"></lucide-angular>
```

#### After
```html
<svg lucideCircleCheck></svg>
```

### B. Static icons with icon data binding

#### Before
```ts
import { CircleCheck } from 'lucide-angular';
```

```html
<lucide-icon [img]="CircleCheck"></lucide-icon>
```

#### After

```ts
import { LucideCircleCheck } from '@lucide/angular';
```

```html
<svg lucideCircleCheck></svg>
```

...and import `LucideCircleCheck` from `@lucide/angular`.

---

### C. Dynamic icons

If the icon varies at runtime, use the dynamic component:

#### Before
```html
<lucide-icon [name]="item.icon"></lucide-icon>
```

#### After
```html
<svg [lucideIcon]="item.icon"></svg>
```

---

## Step 4 – Replace `LucideIconConfig` with `provideLucideConfig()`

### Before
```ts
import { inject } from '@angular/core';
import { LucideIconConfig } from 'lucide-angular';

inject(LucideIconConfig).size = 12;
```

### After
```ts
import { provideLucideConfig } from '@lucide/angular';

providers: [
  provideLucideConfig({ size: 12 }),
]
```

### Where to place it

- App-wide: `AppModule.providers` or `bootstrapApplication(...providers)`
- Feature-level: feature module providers
- Component-level (standalone): component `providers`

---

## Troubleshooting

### The icon is not being displayed
If using per-icon-components:
1. Ensure that the icon component is being imported, if using per-icon-components
2. Check that the icon name matches exactly (case-sensitive)

If using the dynamic component:
1. Ensure the icon is provided via `provideLucideIcons()` if using string names
2. Verify the icon is imported from `@lucide/angular` and not the legacy package

### TypeScript errors?
Make sure you're importing from `@lucide/angular` and not `lucide-angular`.

### Icons render with wrong defaults
Ensure `provideLucideConfig()` is used at the right level.
---

## Removed Brand Icons

Brand icons are removed in v1. If you are using any of the following icons, you will need to replace them with a custom SVG or an alternative icon:

- Chromium
- Codepen
- Codesandbox
- Dribbble
- Facebook
- Figma
- Framer
- Github
- Gitlab
- Instagram
- LinkedIn
- Pocket
- RailSymbol (based on the British Rail logo)
- Slack

We recommend to use the official SVG icons provided by the respective brands, most of them can be found on their websites or in their brand guidelines. Alternatively, you can use the icons from [Simple Icons](https://simpleicons.org/), which provides a large collection of brand icons. Also with links to the official Brand Guidelines and SVG icons.

An [Angular package for Simple Icons](https://github.com/gridatek/semantic-icons/tree/main/libs/simple-icons) with standalone component support is also available.

---

## TL;DR
- `LucideAngularModule` ⇒ static: removed; dynamic: `LucideIcon`
- `LucideAngularModule.pick(...)` ⇒ `provideLucideIcons(...)`
- `<lucide-angular name="foo-bar">` ⇒ `<svg lucideFooBar>`
- `<lucide-icon [name]="expr">` ⇒ `<svg [lucideIcon]="expr">`
- `<lucide-icon [img]="expr">` ⇒ `<svg [lucideIcon]="expr">`
- `LucideIconConfig` ⇒ `provideLucideConfig(...)`
- Replace brand icon usages with [`simple-icons`](https://github.com/gridatek/semantic-icons/tree/main/libs/simple-icons).
