lucide/docs/guide/icons/index.md

# @lucide/icons

`@lucide/icons` is a helper library that exports Lucide **icon data** in a tree-shakable format, also providing utilities for dynamic importing icons.

It intentionally ships **no real rendering logic or components** — but you can use this package to build third-party integrations for frameworks we don't (yet) support.

## Installation

::: code-group

```sh [pnpm]
pnpm add @lucide/icons
```

```sh [yarn]
yarn add @lucide/icons
```

```sh [npm]
npm install @lucide/icons
```

```sh [bun]
bun add @lucide/icons
```

:::

## Icon data format

Each icon is described by the following interface:

```typescript
export type LucideIconData = {
  name: string;
  node: LucideIconNode[];
} & ({ size: number } | { width: number; height: number });
```

| name                         | type               | description                                                        |
| ---------------------------- | ------------------ | ------------------------------------------------------------------ |
| `name`                       | `string`           | The name of the icon.                                              |
| `node`                       | `LucideIconNode[]` | SVG child nodes as `[tagName, attributes]` tuples.                 |
| `size` or `width` & `height` | `number`           | The dimensions of the icon (`size` is shorthand for square icons). |

## How to use

Icons can be imported individually. Only the icons you import end up referenced by your application code — the rest will be eliminated by tree-shaking.

```ts
import { House } from '@lucide/icons';
// House is icon data (not a rendered component).
```

## Building icons

`@lucide/icons` ships small helpers that convert Lucide icon data into different render-ready outputs.
All builders accept the same `params` object (`LucideBuildParams`) to customize the generated SVG.

### Build parameters

The following parameters are supported (names reflect the current implementation):

| param              | type                     | effect                                                                                                                                             |
| ------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `color`            | `string`                 | Sets `stroke` (defaults to `currentColor`).                                                                                                        |
| `size`             | `number`                 | Sets both `width` and `height` (defaults to 24).                                                                                                   |
| `width`            | `number`                 | Sets `width` only.                                                                                                                                 |
| `height`           | `number`                 | Sets `height` only.                                                                                                                                |
| `strokeWidth`      | `number`                 | Sets `stroke-width` (defaults to 2).                                                                                                               |
| `nonScalingStroke` | `boolean`                | Adds [`vector-effect="non-scaling-stroke"`](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/vector-effect) to child elements. |
| `className`        | `string`                 | Appended to the generated `class` attribute.                                                                                                       |
| `attributes`       | `Record<string, string>` | Add or override any generated SVG attributes (including `class`, `viewBox`, and so on).                                                            |

::: info
SVG attributes generated by the builders include a default Lucide setup (`xmlns`, `viewBox`, `fill="none"`, `stroke="currentColor"`, `stroke-width="2"`, `stroke-linecap="round"`, `stroke-linejoin="round"`), plus a class string of the form: `lucide lucide-{iconName}`.
:::

### `buildLucideIconNode`

Creates a root SVG node in an svgson-like format:

```ts
import { buildLucideIconNode } from '@lucide/icons/builders';
import { House } from '@lucide/icons';

const node = buildLucideIconNode(House, {
  size: 32,
  strokeWidth: 1.5,
  className: 'my-icon',
});

// -> ['svg', attributes, children]
```

This is useful if you want to plug Lucide icons into your own renderer, templating system, or framework integration.

### `buildLucideSvg`

Creates an SVG string:

```ts
import { buildLucideSvg } from '@lucide/icons/builders';
import { House } from '@lucide/icons';

const svg = buildLucideSvg(House, { size: 24, color: '#111' });
```

### `buildLucideIconElement`

Creates an actual DOM element (SVG) within the provided document:

```ts
import { buildLucideIconElement } from '@lucide/icons/builders';
import { House } from '@lucide/icons';

const el = buildLucideIconElement(document, House, { size: 24 });
document.body.appendChild(el);
```

### `buildLucideDataUri`

Creates a base64-encoded SVG data URI from a Lucide icon object.

This helper works in both browsers and Node.js:

- In browsers it uses `btoa` (with proper UTF-8 handling)
- In Node.js it falls back to `Buffer`

```ts
import { buildLucideDataUri } from '@lucide/icons/builders';
import { House } from '@lucide/icons';

const uri = buildLucideDataUri(House, { size: 24 });
```

The returned value can be used directly in places such as:

- `<img src="...">`
- CSS `background-image`
- Canvas drawing
- Inline data URLs in HTML or SVG

::: tip Environment notes
The SVG is encoded as UTF-8 before base64 conversion to ensure correct handling of non-ASCII characters.

No runtime configuration is required. The function automatically selects the appropriate encoding strategy.

If neither `btoa` nor `Buffer` is available, an error is thrown.
:::

## Dynamic imports

Dynamic imports are useful when you only know the icon name at runtime (for example, icon names stored in a database or a CMS). For purely static use cases, prefer direct imports for the best tree-shaking results.

::: tip
Validate `iconName` before indexing the map (and provide a fallback icon) to avoid runtime errors.
:::

## Dynamic imports

Dynamic imports are useful when the icon name is only known at runtime (for example, icon names stored in a CMS or database). For purely static usage, prefer direct imports for maximum tree-shaking.

```ts
import { lucideDynamicIconImports } from '@lucide/icons/dynamic';

const name = 'house';
const icon = await lucideDynamicIconImports[name]?.();

if (!icon) {
  // handle unknown icon name (fallback)
}
```