mirror of
https://github.com/lucide-icons/lucide.git
synced 2026-11-17 14:28:25 +00:00
feat(packages): added new @lucide/icons package (#3881)
* 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>
This commit is contained in:
@@ -153,5 +153,23 @@
|
||||
"href": "https://www.npmjs.com/package/lucide-static"
|
||||
}
|
||||
]
|
||||
},
|
||||
"@lucide/icons": {
|
||||
"docsAlias": "icons",
|
||||
"packageDirname": "icons",
|
||||
"order": 10,
|
||||
"icon": "ts",
|
||||
"shields": [
|
||||
{
|
||||
"alt": "npm",
|
||||
"src": "https://img.shields.io/npm/v/@lucide/icons",
|
||||
"href": "https://www.npmjs.com/package/@lucide/icons"
|
||||
},
|
||||
{
|
||||
"alt": "npm",
|
||||
"src": "https://img.shields.io/npm/dw/@lucide/icons",
|
||||
"href": "https://www.npmjs.com/package/@lucide/icons"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -104,6 +104,10 @@ const sidebar: UserConfig<DefaultTheme.Config>['themeConfig']['sidebar'] = {
|
||||
text: 'Lucide Static',
|
||||
link: '/guide/packages/lucide-static',
|
||||
},
|
||||
{
|
||||
text: 'Icon data & helpers',
|
||||
link: '/guide/packages/icons',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
@@ -79,6 +79,16 @@ declare module "lucide-react-native" {
|
||||
}
|
||||
```
|
||||
|
||||
```ts [@lucide-icons]
|
||||
declare module "@lucide/icons" {
|
||||
// Prefixed import names
|
||||
export * from "@lucide/icons/dist/lucide-icons.prefixed";
|
||||
// or
|
||||
// Suffixed import names
|
||||
export * from "@lucide/icons/dist/lucide-icons.suffixed";
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
Place this in your project root or in a folder where your tsconfig.json is located, or locate it in your defined type directory.
|
||||
|
||||
@@ -0,0 +1,172 @@
|
||||
# @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`](http://npmjs.com/package/@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
|
||||
|
||||
```sh [pnpm]
|
||||
pnpm install @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). |
|
||||
| `absoluteStrokeWidth` | `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`, 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:
|
||||
|
||||
```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)
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none" viewBox="0 0 24 24">
|
||||
<path fill="#3178C6" d="M24 0H0v24h24V0Z"/>
|
||||
<path fill="#fff" fill-rule="evenodd" d="M14.11 18.797v2.588c.421.215.918.375 1.49.487a9.45 9.45 0 0 0 1.819.16 8.35 8.35 0 0 0 1.772-.179 4.407 4.407 0 0 0 1.472-.59c.421-.272.75-.628 1.003-1.07.243-.44.365-.983.365-1.63 0-.47-.065-.882-.206-1.238a2.98 2.98 0 0 0-.61-.947 4.48 4.48 0 0 0-.946-.74 11.05 11.05 0 0 0-1.247-.62c-.338-.14-.647-.27-.919-.412a4.124 4.124 0 0 1-.684-.403 1.784 1.784 0 0 1-.44-.44.928.928 0 0 1-.15-.525c0-.178.046-.338.14-.478.093-.141.225-.263.384-.366.169-.103.375-.178.619-.234.244-.057.515-.085.806-.085.216 0 .44.019.684.047.244.028.479.084.722.15.244.066.479.15.713.253.225.103.44.225.637.356v-2.418a6.524 6.524 0 0 0-1.293-.338 10.228 10.228 0 0 0-1.604-.112c-.618 0-1.2.065-1.753.197a4.42 4.42 0 0 0-1.453.618c-.422.282-.75.638-.993 1.07-.244.43-.366.955-.366 1.555 0 .77.225 1.425.666 1.978.45.544 1.125 1.004 2.024 1.388.357.15.685.29.994.431.31.14.572.281.797.44.225.16.403.32.534.498.132.178.197.384.197.61a.921.921 0 0 1-.121.468c-.085.14-.207.262-.366.375-.16.112-.366.187-.619.244a3.957 3.957 0 0 1-.862.084 4.938 4.938 0 0 1-1.67-.3 4.752 4.752 0 0 1-1.537-.872Zm-4.313-6.45h3.328V10.22H3.844v2.128h3.31v9.497h2.633v-9.497h.01Z" clip-rule="evenodd"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 1.3 KiB |
@@ -0,0 +1,9 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="128" height="32" fill="none" viewBox="0 0 128 32">
|
||||
<rect width="128" height="32" rx="8" fill="#fff"/>
|
||||
<path fill="#1b1b1f" d="M78.2 22.17a4.5 4.5 0 0 1-2.27-.55 3.7 3.7 0 0 1-1.46-1.55 5.2 5.2 0 0 1-.5-2.38c0-.9.16-1.69.5-2.37a3.87 3.87 0 0 1 3.62-2.16c.54 0 1.05.09 1.53.26s.9.44 1.27.8.66.81.87 1.37c.22.55.32 1.21.32 1.98v.63h-7.15v-1.4h5.18c0-.4-.09-.74-.25-1.05-.17-.3-.4-.55-.7-.73s-.64-.27-1.04-.27a2 2 0 0 0-1.1.3c-.32.2-.57.47-.75.8q-.255.495-.27 1.08v1.2c0 .52.1.95.28 1.31.19.36.45.64.78.83.33.2.72.29 1.17.29.3 0 .57-.04.81-.13.25-.08.46-.21.63-.38.18-.16.32-.37.4-.62l1.93.22a3 3 0 0 1-.7 1.33c-.33.37-.76.67-1.3.87-.52.2-1.12.31-1.8.31zM67.5 22.15a3.3 3.3 0 0 1-3.13-2.06 5.7 5.7 0 0 1-.47-2.44q0-1.455.48-2.46a3.34 3.34 0 0 1 4.39-1.77c.33.17.59.38.78.62.2.24.34.46.45.68h.08v-4.36h2.07V22h-2.03v-1.38H70c-.1.22-.26.44-.46.68a2.53 2.53 0 0 1-2.04.85m.57-1.68c.44 0 .8-.12 1.12-.36.3-.23.54-.57.7-1 .15-.41.23-.9.23-1.47s-.08-1.06-.24-1.48a2.1 2.1 0 0 0-.69-.97 1.8 1.8 0 0 0-1.12-.34c-.46 0-.84.12-1.15.35-.3.24-.53.57-.69 1-.15.41-.23.9-.23 1.44s.08 1.03.23 1.46c.16.42.4.76.7 1 .31.24.7.37 1.14.37M60.09 22v-8.73h2.05V22zm1.03-9.97a1.2 1.2 0 0 1-1.101-.677 1 1 0 0 1-.09-.433c0-.31.12-.57.35-.79q.36-.33.84-.33.495 0 .84.33a1.045 1.045 0 0 1 0 1.58c-.23.22-.5.32-.84.32M54.66 22.17a3.83 3.83 0 0 1-3.68-2.16 5.24 5.24 0 0 1-.5-2.34c0-.89.17-1.67.51-2.35s.82-1.2 1.44-1.59a4.16 4.16 0 0 1 2.22-.57c.7 0 1.33.13 1.88.4a3.21 3.21 0 0 1 1.87 2.74h-1.97a1.88 1.88 0 0 0-.56-1.06q-.45-.42-1.2-.42c-.41 0-.78.11-1.1.34-.32.22-.57.54-.74.96-.18.43-.27.93-.27 1.52 0 .6.1 1.1.27 1.53.17.42.41.75.73.98s.69.34 1.12.34c.3 0 .57-.05.81-.17.24-.11.45-.28.6-.5.17-.22.28-.49.34-.8h1.97a3.23 3.23 0 0 1-1.83 2.76 4.3 4.3 0 0 1-1.9.39zM46.68 18.33v-5.06h2.06V22h-2v-1.55h-.09c-.2.49-.52.89-.97 1.2-.45.3-1 .46-1.65.46a2.64 2.64 0 0 1-2.54-1.5 3.95 3.95 0 0 1-.37-1.78v-5.56h2.06v5.24c0 .55.15 1 .45 1.32.3.33.7.49 1.2.49a1.89 1.89 0 0 0 1.57-.88c.19-.3.28-.67.28-1.11M32.15 22V10.36h2.1v9.87h5.13V22z"/>
|
||||
<path stroke="#1b1b1f" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M18 16a4 4 0 1 0-8 0 8 8 0 0 0 16 0c0-3.55-1.55-6.75-4-8.94"/>
|
||||
<path stroke="#f56565" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M14 16a4 4 0 1 0 8 0 8 8 0 0 0-16 0c0 3.58 1.57 6.8 4.06 9"/>
|
||||
<path fill="#ddd" d="M92 18a2 2 0 1 0 0-4 2 2 0 0 0 0 4"/>
|
||||
<path fill="#3178c6" d="M122 6h-20v20h20z"/>
|
||||
<path fill="#fff" fill-rule="evenodd" d="M113.758 21.664v2.157q.526.267 1.242.406.751.14 1.516.133c.496.003.991-.047 1.476-.15a3.7 3.7 0 0 0 1.227-.49 2.54 2.54 0 0 0 .836-.893q.303-.55.304-1.358c0-.392-.054-.735-.172-1.032a2.5 2.5 0 0 0-.508-.789 3.7 3.7 0 0 0-.788-.616 9 9 0 0 0-1.04-.517 10 10 0 0 1-.765-.343 3.4 3.4 0 0 1-.57-.336 1.5 1.5 0 0 1-.367-.367.77.77 0 0 1-.125-.437q0-.223.117-.399c.077-.117.187-.219.32-.305.14-.086.312-.148.515-.195q.308-.07.672-.07c.18 0 .367.015.57.039.203.023.399.07.602.125q.303.082.594.21c.187.086.367.188.531.297V14.72a5.5 5.5 0 0 0-1.078-.282 8.5 8.5 0 0 0-1.336-.093q-.771 0-1.461.164a3.7 3.7 0 0 0-1.211.515 2.6 2.6 0 0 0-.828.892c-.203.358-.305.796-.305 1.296 0 .641.188 1.187.555 1.648q.563.678 1.687 1.157c.298.125.571.241.828.359.259.117.477.234.665.367.187.133.335.266.445.415s.164.32.164.508a.76.76 0 0 1-.101.39 1.1 1.1 0 0 1-.305.312 1.4 1.4 0 0 1-.516.204 3.3 3.3 0 0 1-.718.07 4.1 4.1 0 0 1-1.392-.25 4 4 0 0 1-1.28-.727m-3.594-5.375h2.773v-1.772h-7.734v1.773h2.758v7.914h2.195V16.29z" clip-rule="evenodd"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 3.5 KiB |
Reference in New Issue
Block a user