* feat(packages): added lucide icons package skeleton
* feat(packages): added initial commit of @lucide/icons
* fix: fixed linting issues introduced in c4e5730bc4 (#3858)
* fix(packages/icons): update package, remove UMD export
* fix(packages/icons): update github actions
* docs(packages/icons): add documentation for various helpers and types
* fix(.github/ISSUE_TEMPLATE): fix linting issue (@ is a reserved character)
* fix(packages/icons): fix linting issues in configs
* feat(packages/icons): rename from packages/lucide-icons => packages/icons
* fix(pnpm): update lockfile
* fix(packages/icons): update readme and documentation
* fix(packages/icons): update absoluteStrokeWidth implementation
* test(packages/icons): update absoluteStrokeWidth unit test
* feat(packages/icons): add backwards compatible alias support in buildLucideIconNode
* feat(packages/icons): fix linting issues in build tools
* fix(packages/icons): rename LucideIcon => LucideIconData
---------
Co-authored-by: Eric Fennis <eric.fennis@gmail.com>
6.4 KiB
@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 install @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
btoanorBufferis 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)
}