Mirrors/lucide
1
0
Fork 0
mirror of https://github.com/lucide-icons/lucide.git synced 2025-12-16 19:27:42 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs(packages/lucide-static): update docs for better clarity (#3225)

Browse Source 
* docs(packages/lucide-static): update docs for better clarity

* docs(packages/lucide-static): fix node.js heading level
This commit is contained in:
Karsa
2025-06-24 13:18:07 +02:00
committed by GitHub
parent 87a67cc314
commit a87ac013f7
2 changed files with 115 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/.vitepress/lib/codeExamples/createCodeExamples.ts
View File

@@ -1,5 +1,4 @@
import { bundledLanguages, type ThemeRegistration } from 'shikiji';
import { getHighlighter } from 'shikiji';
import { bundledLanguages, getHighlighter, type ThemeRegistration } from 'shikiji';
type CodeExampleType = {
title: string;
@@ -102,13 +101,8 @@ import { LucideAngularModule, $PascalCase } from 'lucide-angular';
},
{
language: 'html',
title: 'Icon Font',
code: `<style>
@import ('~lucide-static/font/Lucide.css');
</style>
<div class="icon-$Name"></div>
`,
title: 'Icon font',
code: `<div class="icon-$Name"></div>`,
},
];
};

172
docs/guide/packages/lucide-static.md
View File

@@ -1,24 +1,38 @@
# Lucide Static
This package include the following lucide implementations:
This package includes the following implementations of Lucide icons:
- All SVG files
- Individual SVG files
- SVG sprite
- Icon fonts
- JavaScript library containing strings of SVGs.
- Icon font files
- A JavaScript library exporting SVG strings
## Why lucide-static?
## Who is this for?
This package is suitable for specific use cases, for example if you want to use icon fonts, SVG sprites, normal SVGs or Common.js SVG strings in your javascript project.
`lucide-static` is suitable for _very specific use cases_ where you want to use Lucide icons without relying on a JavaScript framework or component system. It's ideal for:
::: warning
While they can be useful for prototyping, it is not recommended to use the SVG sprites or icon fonts provided by this package in production web apps as all the available icons are included in the app, hence increasing loading time and data usage. We recommend to use a bundler and tree-shaking to make sure only the icons you use are bundled with your app. Tree-shaking is only available in these packages: [lucide](lucide), [lucide-react](lucide-react), [lucide-vue](lucide-vue), [lucide-vue-next](lucide-vue-next), [lucide-angular](lucide-angular), [lucide-preact](lucide-preact)
- Projects that use icon fonts with plain CSS or utility-first frameworks
- Embedding raw SVG files or sprites directly in HTML
- Using SVGs as CSS background images
- Importing SVG strings into Node.js (CommonJS) environments
::: danger
### Not recommended for production {#production-warning}
SVG sprites and icon fonts include **all icons**, which can significantly increase your app's bundle size and load time.
For production environments, we recommend using a bundler with tree-shaking support to include only the icons you actually use. Consider using:
- [lucide](lucide)
- [lucide-react](lucide-react)
- [lucide-vue](lucide-vue)
- [lucide-vue-next](lucide-vue-next)
- [lucide-angular](lucide-angular)
- [lucide-preact](lucide-preact)
:::
## Installation
## Package Managers
::: code-group
```sh [pnpm]
@@ -39,64 +53,77 @@ bun add lucide-static
:::
### CDN
## SVG Files
```html
<!-- SVG file for a single icon -->
<img src="https://unpkg.com/lucide-static@latest/icons/house.svg" />
You can use standalone SVG files or SVG sprites in several ways.
<!-- Icon font -->
<style>
@font-face {
font-family: 'LucideIcons';
src: url(https://unpkg.com/lucide-static@latest/font/Lucide.ttf) format('truetype');
}
</style>
```
Check out our [codesandbox example](https://codesandbox.io/s/using-the-svg-sprite-lz1kk).
## Usage
### SVG file as image
Check out the [codesandbox examples](https://codesandbox.io/s/using-the-svg-sprite-lz1kk).
#### In HTML:
### SVG Files
::: code-group
#### SVG file as image
To use it in for example html:
```html
```html [Webpack]
<!-- SVG file for a single icon -->
<img src="~lucide-static/icons/house.svg" />
```
```css
```html [CDN]
<!-- SVG file for a single icon -->
<img src="https://unpkg.com/lucide-static@latest/icons/house.svg" />
```
:::
#### In CSS:
::: code-group
```css [Webpack]
.house-icon {
background-image: url(~lucide-static/icons/house.svg);
}
```
Make sure you have the correct webpack loaders to make this work. [url-loader](https://v4.webpack.js.org/loaders/url-loader/)
```css [CDN]
.house-icon {
background-image: url(https://unpkg.com/lucide-static@latest/icons/house.svg);
}
```
#### SVG file as string
:::
You can simply import each SVG by targeting `lucide-static/icons/{icon-name}.svg`.
To use SVGs in your project you can for example use a [SVG loader](https://v4.webpack.js.org/loaders/svg-inline-loader/).
Make sure you have the correct Webpack loader configured, such as [`url-loader`](https://v4.webpack.js.org/loaders/url-loader/).
### SVG file as string
To import an SVG as a string (e.g., for templating):
```js
import arrowRightIcon from 'lucide-static/icons/arrow-right';
// return string of an SVG
```
### SVG Sprite
You'll need an SVG loader like [`svg-inline-loader`](https://v4.webpack.js.org/loaders/svg-inline-loader/).
You may need additional loader for this.
### Using the SVG sprite
:::danger
[Not intended for production use.](#production-warning)
:::
You may also need an additional SVG loader to handle this.
#### Basic sprite usage (not production-optimized):
```html
<!-- Icon Sprite, not recommended for production! -->
<img src="lucide-static/sprite.svg#house" />
```
<!-- or -->
#### Inline usage:
```html
<svg
width="24"
height="24"
@@ -109,12 +136,13 @@ You may need additional loader for this.
<use href="#alert-triangle" />
</svg>
<svg>
...sprite svg
</svg>
<!-- sprite SVG -->
<svg>...</svg>
```
If you'd prefer, you can use CSS to hold your base SVG properties
#### Inline with CSS helper class
If you'd prefer, you can use CSS to hold your base SVG properties:
```css
.lucide-icon {
@@ -128,47 +156,71 @@ If you'd prefer, you can use CSS to hold your base SVG properties
}
```
and update the SVG as follows
...and update the SVG as follows:
```xml
<svg
xmlns="http://www.w3.org/2000/svg"
class="lucide-icon"
>
<use
href="#triangle-alert"
/>
</svg>
<svg>
...sprite svg
<use href="#triangle-alert" />
</svg>
<!-- sprite SVG -->
<svg>...</svg>
```
### Icon Font
## Icon font
```css
:::danger
[Not intended for production use.](#production-warning)
:::
Lucide icons are also available as a web font. To use them, you first need to include the corresponding stylesheet:
::: code-group
```css [Vite]
@import 'lucide-static/font/lucide.css';
```
```css [Webpack]
@import ('~lucide-static/font/lucide.css');
```
```html [CDN]
<link rel="stylesheet" href="https://unpkg.com/lucide-static@latest/font/lucide.css" />
```
```html [Static asset]
<link rel="stylesheet" href="/your/path/to/lucide.css" />
```
:::
Once included, use the format `icon-{kebab-case-name}`. You can copy icon names from the [Lucide Icons page](https://lucide.dev/icons).
```html
<div class="icon-house"></div>
```
### Node.js
If you're not using a package manager, you can download the font files directly from the [latest release](https://github.com/lucide-icons/lucide/releases/latest).
To use lucide icons in your Nodejs project you can import each icon as:
## Node.js
You can also import Lucide icons in Node.js (CommonJS) projects:
```js
const { messageSquare } = require('lucide-static/lib');
const {messageSquare} = require('lucide-static/lib');
```
> Note: Each icon name is in camelCase.
#### Example in node.js project
#### Express app example in Node.js
```js
const express = require('express');
const { messageSquare } = require('lucide-static/lib');
const {messageSquare} = require('lucide-static/lib');
const app = express();
const port = 3000;
@@ -181,7 +233,7 @@ app.get('/', (req, res) => {
</head>
<body>
<h1>Lucide Icons</h1>
<p>This is a lucide icon ${messageSquare}</p>
<p>This is a Lucide icon ${messageSquare}</p>
</body>
</html>