You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<h2>The most performant way to do icons in React</h2>
7
+
<h1>React Zero Icon Sprite - Zero Runtime SVG Icons</h1>
8
+
<h2>The most performant way to use icons in React</h2>
9
+
10
+
<legend><b>Use over 6,800+</b> Lucide & Tabler <code><Icon /></code> in development. </br> Ship <b>one SVG sprite</b> in production - only the icons you used.</legend>
11
+
12
+
<br/>
13
+
14
+
<tablealign="center">
15
+
<tr>
16
+
<td align="center" width="33%">
17
+
🚀 <b>Zero Runtime</b><br/>Compiles to native <code><use></code> tags
18
+
</td>
19
+
<td align="center" width="33%">
20
+
📦 <b>~300% Smaller</b><br/>No HTML bloat or JS overhead
21
+
</td>
22
+
<td align="center" width="33%">
23
+
🎨 <b>6,800+ Icons</b><br/>Full Lucide & Tabler support
🧩 <b>Custom Icons</b><br/>First-class support for your SVGs
35
+
</td>
36
+
</tr>
37
+
</table>
9
38
10
-
<legend><b>Use over 1,600</b> Lucide <code><Icon /></code> in development. </br> Ship <b>one SVG sprite</b> in production - only the icons you used.</legend>
11
-
<small>Average 300% Decrease in HTML Size. <atarget="_blank"href="https://zero-ui.dev/icon-sprite">See the Demo ↗︎</a></small>
12
-
13
-
<p/>
14
-
<p/>
15
-
<p>
16
-
🔹 Zero runtime 🔹 Tree-shaken & deduped 🔹 Lucide + your custom SVGs 🔹 Long-cacheable sprite 🔹 SSR-safe
17
-
</p>
18
39
</div>
19
40
41
+
---
20
42
21
-
```jsx
22
-
// Development (DX)
23
-
import { Icon } from"@react-zero-ui/icon-sprite";
43
+
## Contents
24
44
25
-
<ArrowRight props="..."/>;
26
-
```
27
-
Automaitcally generates:
28
-
```html
29
-
<!-- Production output (zero runtime) -->
30
-
<svgprops="...">
31
-
<usehref="/icon.svg#arrow-right" />;
32
-
</svg>
45
+
-[Why This Library?](#why-this-library)
46
+
-[Benchmarks](#-benchmarks-150-icons)
47
+
-[Quick Start](#quick-start)
48
+
-[Usage](#usage)
49
+
-[How It Works](#how-it-works-under-the-hood)
33
50
34
-
```
51
+
---
35
52
36
-
Quick Start
53
+
## Why This Library?
37
54
38
-
```
39
-
npm install @react-zero-ui/icon-sprite
55
+
SVG sprites are still the most performant way to deliver flat icons on the web. They are significantly smaller than React components and can be cached aggressively by the browser.
40
56
41
-
```
57
+
**However, using sprites in development is a pain.**
58
+
Browsers cache sprites so aggressively that you often have to close the tab and reopen it just to see a new icon, even with cache disabled in DevTools.
42
59
43
-
44
-
45
-
Part of the [React Zero-UI](https://github.com/react-zero-ui) ecosystem.
46
-
47
-
60
+
**This library solves that problem:**
61
+
1.**In Development:** It uses standard React components. No caching issues, instant HMR (Hot Module Replacement), and full prop support.
62
+
2.**In Production:** It compiles everything into a single, highly optimized SVG sprite that is loaded once and cached forever.
48
63
49
-
---
64
+
You get the **Developer Experience** of a component library with the **Performance** of a handwritten sprite.
50
65
51
-
52
66
> [!NOTE]
53
-
>**Live Demo ~270% Smaller HTML**
54
-
>**See the difference:**[View Demo](https://zero-ui.dev/icon-sprite)
55
-
56
-
67
+
> **See the difference for yourself:**[View Live Demo ↗](https://zero-ui.dev/icon-sprite)
57
68
58
69
---
59
70
71
+
## ⚡ Benchmarks (150 Icons)
60
72
61
-
## What This Library Does
62
-
63
-
1.**Full Lucide-React DX in development**
64
-
Easy imports, hot reload, JSX props - import icons from `@react-zero-ui/icon-sprite` instead of `lucide-react`.
73
+
| Library | HTML Size |
74
+
|---------|-----------|
75
+
|**LucideReact**| 19.5kb |
76
+
|**@react-zero-ui**|**7.5kb**|
65
77
66
-
2.**Zero-runtime in production**
67
-
Every icon becomes `<use href="/icons.svg#id" />` at build time.
78
+
---
68
79
69
-
3.**Smallest possible sprite**
70
-
Only icons actually used in your app are included.
80
+
## Quick Start
71
81
72
-
## Custom Icon Support
73
-
Drop SVGs into **`/public/zero-ui-icons/`**, then use `<CustomIcon />` with the filename (no `.svg`).
82
+
### 1. Install
74
83
75
-
> [!TIP]
76
-
>```txt
77
-
>📁/public
78
-
> └──📁/zero-ui-icons/
79
-
> └──dog.svg
80
-
> ```
81
-
> ```tsx
82
-
>import { CustomIcon } from "@react-zero-ui/icon-sprite";
83
-
>//❗The name MUST matcb the file name (no .svg extension).
84
-
><CustomIcon name="dog" size={24} />
85
-
>```
86
-
87
-
> [!NOTE]
88
-
> In dev you may see a brief FOUC using custom icons; this is removed in production.
84
+
```bash
85
+
npm install @react-zero-ui/icon-sprite
86
+
```
89
87
90
-
---
88
+
### 2. Use Icons
91
89
92
-
## Installation
90
+
```tsx
91
+
import { ArrowRight, Mail } from"@react-zero-ui/icon-sprite";
93
92
94
-
```bash
95
-
npm install @react-zero-ui/icon-sprite
93
+
<ArrowRightsize={24}className="text-gray-600" />
94
+
<Mailwidth={24}height={24} />
96
95
```
97
96
98
-
---
97
+
### 3. Build for Production
99
98
100
-
## Build Command
101
99
> [!CAUTION]
102
-
> Run this before your app build so the sprite exists.
103
-
>```bash
104
-
>npx zero-icons
105
-
>```
100
+
> Run this **before** your app build so the sprite exists.
106
101
107
-
This command builds the icons sprite for production.
102
+
```bash
103
+
npx zero-icons
104
+
```
108
105
109
-
Or add this to your `package.json` scripts:
106
+
Or add it to your `package.json`:
110
107
```json
111
108
{
112
109
"scripts": {
@@ -115,17 +112,14 @@ Or add this to your `package.json` scripts:
115
112
}
116
113
}
117
114
```
118
-
That's it! You can now use the icons in your app.
115
+
116
+
That's it! Your icons are now optimized for production.
119
117
120
118
---
121
119
122
120
## Usage
123
121
124
-
> [!WARNING]
125
-
> **Pass `size`, or both `width` and `height`, to ensure identical dev/prod rendering.**
126
-
> Dev defaults (Lucide 24×24) differ from sprite viewBoxes in production. Missing these props will **very likely** change the visual size in prod.
127
-
128
-
### For Lucide Icons:
122
+
### Lucide Icons
129
123
130
124
```tsx
131
125
import { ArrowRight, Mail } from"@react-zero-ui/icon-sprite";
@@ -134,19 +128,42 @@ import { ArrowRight, Mail } from "@react-zero-ui/icon-sprite";
134
128
<Mailwidth={24}height={24} />
135
129
```
136
130
137
-
### Custom Icons:
131
+
### Tabler Icons
138
132
139
-
Drop SVGs into **`/public/zero-ui-icons/`**, then use `<CustomIcon />` with the filename (no `.svg`).
0 commit comments