Contents

• Why This Library?
• Quick Start
• Usage
• Configuration
• How It Works

Why This Library?

Most React icon packages make you choose an icon set up front, then ship each icon as component-level SVG geometry.

React Zero Icon Sprite takes a different approach:

1. One package: Lucide and Tabler share one React API, with more icon sets able to join the same catalog over time.
2. Build-time discovery: zero-icons scans your source and finds the icons your app actually uses.
3. One production sprite: Used built-in icons and your custom SVGs are compiled into a single cacheable sprite.
4. Small production markup: Icon components render native <svg><use /></svg> references instead of repeating SVG geometry.

You can choose from thousands of icons during development while production ships only the geometry your application needs.

[!NOTE] View the live demo

Quick Start

1. Install

npm install @react-zero-ui/icon-sprite

React 17+ is supported. The zero-icons build step requires Node.js 22.18+ on Node 22, or Node.js 24.11+.

2. Use Icons

import { ArrowRight, Mail } from "@react-zero-ui/icon-sprite";

<ArrowRight size={24} className="text-gray-600" />
<Mail width={24} height={24} />

3. Build for Production

[!CAUTION] Run this before your app build so the sprite exists.

npx zero-icons

Or add it to your package.json:

{
  "scripts": {
    "prebuild": "zero-icons",
    "build": "your build command"
  }
}

That's it. zero-icons scans your source and writes public/icons.svg before your application build.

Usage

[!NOTE] Style the outer <svg> through props or className. Descendant selectors such as .icon path apply only to development's inline SVGs; production sprites use an isolated shadow tree.

Lucide Icons

import { ArrowRight, Mail } from "@react-zero-ui/icon-sprite";

<ArrowRight size={24} className="text-gray-600" />
<Mail width={24} height={24} />

Tabler Icons

tabler icons are imported with the Icon prefix, e.g. IconBrandGithub

import { IconBrandGithub, IconHeart } from "@react-zero-ui/icon-sprite";

<IconBrandGithub size={24} className="text-gray-600" />
<IconHeart width={24} height={24} />

Tabler Filled Icons

Use the Filled suffix for Tabler's filled designs. Color follows currentColor, so text-color classes and the color prop work in development and production.

import { IconHeartFilled, IconStarFilled } from "@react-zero-ui/icon-sprite";

<IconHeartFilled size={24} className="text-red-500" />
<IconStarFilled size={24} color="gold" />

Used outline and filled icons share the same production sprite. Filled components are available for Tabler's filled catalog.

Custom Icons

Place SVGs anywhere under your app's public/ directory and pass their root-relative URLs to <CustomIcon />:

[!TIP]

public/
 brand/
   logo.svg

import { CustomIcon } from "@react-zero-ui/icon-sprite";

<CustomIcon src="/brand/logo.svg" size={24} />

The required src prop replaces name. The build includes only referenced SVGs. Write src as an inline string, such as src="/brand/logo.svg" or src={"/brand/logo.svg"}, after any JSX spreads. Variables, computed expressions, remote URLs, and symlinks are unsupported. Missing files and paths targeting the generated sprite fail the build.

[!NOTE] Development fetches the source SVG and displays it inline, so a brief flash may occur before loading. Production uses the sprite. Style the outer SVG; descendant CSS selectors cannot reach artwork inside an external sprite.

Configuration

Most apps need no configuration. If your source lives somewhere other than src, app, or pages, add zero-ui.config.ts:

import type { ZeroUIConfig } from "@react-zero-ui/icon-sprite"

export default {
  ROOT_DIR: "frontend",
} satisfies ZeroUIConfig

The config also supports scan exclusions, package import names, and sprite output locations. Custom SVGs use their src paths under public/; no custom icon directory setting is needed.

How It Works (Under the Hood)

export function ArrowRight(props) {
  if (process.env.NODE_ENV !== "production") {
    return <svg {...props}>{/* packaged SVG geometry */}</svg>
  }

  return <svg {...props}><use href="/icons.svg#arrow-right" /></svg>
}

Part of the React Zero-UI ecosystem.

Created by and maintained by Serbyte Development