lucide/docs/guide/packages/icons.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 — 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; }
);

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.

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).
absoluteStrokeWidth	boolean	Adds vector-effect="non-scaling-stroke" 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, etc.).

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

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

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

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

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