svg-sprites/docs/en/guides/react-vite.md

# SVG Sprite for React with Vite

A quick guide to creating an SVG sprite in a React application built with Vite.

## Generate the sprite

Choose a folder for the sprite. This example uses `assets/app-icons`, with source SVG files, including the `check.svg` used below, in `assets/svg-icons`.

Create `assets/app-icons/svg-sprite.config.json`:

```json
{
  "mode": "react@vite",
  "name": "app",
  "input": "../svg-icons/**/*.svg"
}
```

The `input` path is relative to the config folder.

Add generation commands to `package.json`. Generated files are excluded from Git by default, so `predev` and `prebuild` rebuild the sprite before every start and build:

```json
{
  "scripts": {
    "sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",
    "predev": "npm run sprites",
    "dev": "vite",
    "prebuild": "npm run sprites",
    "build": "tsc --noEmit && vite build"
  }
}
```

## Use the sprite

The value `name: "app"` creates the React component `AppIcon`.

Create the entry point `assets/app-icons/index.ts`:

```ts
export * from './.svg-sprite/index.js'
```

Use the component in your application:

```tsx
import { AppIcon } from '../assets/app-icons'

export function SaveIcon() {
  return (
    <AppIcon
      icon="check"
      width={24}
      height={24}
      role="img"
      aria-label="Done"
      style={{
        color: '#334155',
        '--icon-color-2': '#f59e0b',
      }}
    />
  )
}
```

The `icon` prop accepts source SVG file names without the extension. A monochrome icon inherits `color`, while colors in a multicolor icon are overridden with `--icon-color-N`.

Vite automatically includes the component styles and adds `sprite.svg` to the production build.

## Debug and preview

Viewer displays all icons on one page so you can check their rendering, change colors, and inspect the related CSS variables. It is only needed for development and is installed separately:

```bash
npm install --save-dev @gromlab/svg-sprites
```

Create `svg-sprite.html` in the project root:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Project icons</title>
  </head>
  <body>
    <!-- React root for debugging and previewing the SVG sprite in Viewer -->
    <div id="svg-sprite-viewer"></div>

    <!-- Load the debug script created below -->
    <script type="module" src="/src/svg-sprite-debug.tsx"></script>
  </body>
</html>
```

Create `src/svg-sprite-debug.tsx`:

```tsx
import { createRoot } from 'react-dom/client'
import { SpriteViewer } from '@gromlab/svg-sprites/react'

const sources = [
  () => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),
] as const

createRoot(document.getElementById('svg-sprite-viewer')!).render(
  <SpriteViewer sources={sources} title="Project icons" />,
)
```

Run `npm run dev` and open `/svg-sprite.html`.

The standard Vite production build uses only `index.html` and does not include the Viewer page.
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`# SVG Sprite for React with Vite`
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`A quick guide to creating an SVG sprite in a React application built with Vite.`
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`## Generate the sprite`
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Choose a folder for the sprite. This example uses `assets/app-icons`, with source SVG files, including the `check.svg` used below, in `assets/svg-icons`.
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Create `assets/app-icons/svg-sprite.config.json`:
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			```json
			`{`
			`"mode": "react@vite",`
			`"name": "app",`
			`"input": "../svg-icons/*/.svg"`
sync 2026-07-14 16:11:39 +03:00			`}`
			```

style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			The `input` path is relative to the config folder.
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Add generation commands to `package.json`. Generated files are excluded from Git by default, so `predev` and `prebuild` rebuild the sprite before every start and build:
sync 2026-07-14 16:11:39 +03:00
			```json
			`{`
			`"scripts": {`
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`"sprites": "npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json",`
			`"predev": "npm run sprites",`
			`"dev": "vite",`
			`"prebuild": "npm run sprites",`
			`"build": "tsc --noEmit && vite build"`
sync 2026-07-14 16:11:39 +03:00			`}`
			`}`
			```

style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`## Use the sprite`
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			The value `name: "app"` creates the React component `AppIcon`.
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Create the entry point `assets/app-icons/index.ts`:
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			```ts
			`export * from './.svg-sprite/index.js'`
			```

			`Use the component in your application:`
sync 2026-07-14 16:11:39 +03:00
			```tsx
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`import { AppIcon } from '../assets/app-icons'`
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`export function SaveIcon() {`
sync 2026-07-14 16:11:39 +03:00			`return (`
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`<AppIcon`
			`icon="check"`
			`width={24}`
			`height={24}`
			`role="img"`
			`aria-label="Done"`
			`style={{`
			`color: '#334155',`
			`'--icon-color-2': '#f59e0b',`
			`}}`
			`/>`
sync 2026-07-14 16:11:39 +03:00			`)`
			`}`
			```

style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			The `icon` prop accepts source SVG file names without the extension. A monochrome icon inherits `color`, while colors in a multicolor icon are overridden with `--icon-color-N`.
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Vite automatically includes the component styles and adds `sprite.svg` to the production build.
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`## Debug and preview`
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`Viewer displays all icons on one page so you can check their rendering, change colors, and inspect the related CSS variables. It is only needed for development and is installed separately:`
sync 2026-07-14 16:11:39 +03:00
			```bash
			`npm install --save-dev @gromlab/svg-sprites`
			```

style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Create `svg-sprite.html` in the project root:

			```html
			`<!doctype html>`
			`<html lang="en">`
			`<head>`
			`<meta charset="UTF-8">`
			`<title>Project icons</title>`
			`</head>`
			`<body>`
			`<!-- React root for debugging and previewing the SVG sprite in Viewer -->`
			`<div id="svg-sprite-viewer"></div>`

			`<!-- Load the debug script created below -->`
			`<script type="module" src="/src/svg-sprite-debug.tsx"></script>`
			`</body>`
			`</html>`
			```

			Create `src/svg-sprite-debug.tsx`:
sync 2026-07-14 16:11:39 +03:00
			```tsx
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`import { createRoot } from 'react-dom/client'`
sync 2026-07-14 16:11:39 +03:00			`import { SpriteViewer } from '@gromlab/svg-sprites/react'`

			`const sources = [`
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`() => import('../assets/app-icons/.svg-sprite/svg-sprite.manifest.js'),`
			`] as const`
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			`createRoot(document.getElementById('svg-sprite-viewer')!).render(`
			`<SpriteViewer sources={sources} title="Project icons" />,`
			`)`
sync 2026-07-14 16:11:39 +03:00			```

style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			Run `npm run dev` and open `/svg-sprite.html`.
sync 2026-07-14 16:11:39 +03:00
style: Синхронизировать английскую документацию 2026-07-15 13:41:24 +03:00			The standard Vite production build uses only `index.html` and does not include the Viewer page.