@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 — other packages (for example @lucide/angular) can consume this data to render icons in their respective frameworks. You can also use this package to build third-party integrations for frameworks we don't (yet) support.

Installation

::: code-group

pnpm add @lucide/icons

yarn add @lucide/icons

npm install @lucide/icons

bun add @lucide/icons

:::

Icon data format

Each icon is described by the following interface:

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

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.

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):

::: 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:

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:

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:

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

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:

• ``
• 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.

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

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

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