A high-performance Vite plugin that transforms SVG files into an optimized SVG sprite system with framework-specific adapters.

• SVG sprites with <symbol> and <use> for optimized performance
• Built-in React and vanilla JavaScript adapters (custom adapters supported)
• Full TypeScript support with framework-specific type definitions
• Integrated SVGO optimization with automatic ID collision prevention
• HMR support in development mode

npm install @sipgate/vite-plugin-neoicons-sprite --save-dev
# or
pnpm add @sipgate/vite-plugin-neoicons-sprite --save-dev
# or
yarn add @sipgate/vite-plugin-neoicons-sprite --dev

Add the plugin to your vite.config.js or vite.config.ts:

import createSvgSpritePlugin from '@sipgate/vite-plugin-neoicons-sprite';

export default {
  plugins: [
    createSvgSpritePlugin({
      exportType: 'react', // or 'vanilla', 'custom'
      include: '**/*.svg'
    }),
  ],
}

Set exportType: 'react' to import SVG files as React components. The plugin automatically generates icon namespace files for each directory containing SVG files.

Automatic Icon File Generation:

The plugin scans your SVG files and automatically generates namespace files (e.g., SolidNeoIcons.tsx, LineNeoIcons.tsx) in each directory containing SVG files. These files are named based on the directory name (e.g., solid/ → SolidNeoIcons.tsx, line/ → LineNeoIcons.tsx).

Simply import from the auto-generated files:

import { SolidNeoIcons } from "./icons/solid/SolidNeoIcons";
import { LineNeoIcons } from "./icons/line/LineNeoIcons";
import { DuotoneNeoIcons } from "./icons/duotone/DuotoneNeoIcons";

function App() {
  return (
    <div>
      <SolidNeoIcons.Administration size={16} color="blue" />
      <LineNeoIcons.Add size={24} />
      <DuotoneNeoIcons.Announcement size={16} color="red" color2="green" />
    </div>
  );
}

You can also import individual icons directly using the ?sprite query parameter:

import IconHome from './icons/home.svg?sprite';
import IconUser from './icons/user.svg?sprite';

function App() {
  return (
    <div>
      <IconHome className="icon" />
      <IconUser style={{ color: 'blue' }} size={16} />
    </div>
  );
}

Components are memoized. You can use size prop for explicit sizing, and color/color2 props for duotone icons.

With exportType: 'vanilla', imports return a symbol ID string. Use the ?sprite query parameter when importing:

import iconHome from './icons/home.svg?sprite';

const html = `<svg><use href="#${iconHome}" /></svg>`;

Access original SVG attributes via named export:

import iconHome, { attributes } from './icons/home.svg?sprite';
// attributes: { width: "24", height: "24", viewBox: "0 0 24 24" }

Add type definitions to tsconfig.json:

{
  "compilerOptions": {
    "types": ["@sipgate/vite-plugin-neoicons-sprite/typings/react"]
  }
}

Use /typings/vanilla for vanilla mode.

interface SvgSpriteOptions {
  // Pattern(s) to match SVG files for processing
  include?: string | string[];

  // Template for generated symbol IDs
  symbolId?: string;

  // Output type for imported SVGs
  exportType?: 'vanilla' | 'react' | 'custom';

  // Custom adapter path (required if exportType is 'custom')
  adapter?: string;

  // SVGO optimization config
  svgo?: SvgoOptimizeOptions;

  // Whether imports have side effects (sprite injection)
  moduleSideEffects?: boolean;
}

Type: string | string[] Default: '**.svg'

Glob pattern(s) for matching SVG files. Uses micromatch syntax.

include: '**/icons/*.svg'
include: ['**/icons/*.svg', '**/brands/*.svg']

Type: string Default: 'icon-[name]'

Template for symbol IDs. Placeholders: [name] (filename), [hash] (content hash).

symbolId: 'icon-[name]'     // home.svg → "icon-home"
symbolId: '[name]-[hash]'   // home.svg → "home-a1b2c3d4"

Type: 'vanilla' | 'react' | 'custom' Default: 'vanilla'

• 'vanilla' - Exports symbol ID string
• 'react' - Exports React component
• 'custom' - Uses custom adapter (requires adapter option)

Type: string

Path to custom adapter module for exportType: 'custom'.

// custom-adapter.js
export const adapter = (id, name) => ({
  id,
  render: (props) => `<svg ${props}><use href="#${id}" /></svg>`
});

Type: SvgoOptimizeOptions

SVGO configuration. See SVGO docs.

Type: boolean Default: true

Whether SVG imports have side effects (DOM injection). Set to false for better tree-shaking (may break sprite injection).

1. Build: SVG files are optimized with SVGO, converted to <symbol> elements, and a module is generated
2. Runtime: On first import, a hidden sprite container is created in the DOM and symbols are injected
3. Usage: Components/IDs reference symbols via <use href="#symbol-id" />

Each icon's markup appears only once in the DOM, regardless of usage count.

# Install dependencies
pnpm install

# Build the plugin
pnpm build

# Lint and format
pnpm lint
pnpm format

The project uses Biome for linting and formatting.

The package is published to npm under the @sipgate scope as @sipgate/vite-plugin-neoicons-sprite.

1. Update the version in package.json
2. Commit your changes
3. Publish to npm:

pnpm publish

The prepublishOnly script automatically runs pnpm build before publishing, ensuring the latest changes are compiled.

The following files and directories are included in the published package (defined in the files field):

• dist/ - Compiled JavaScript and TypeScript declaration files
• typings/ - TypeScript type definitions for consumers (vanilla, react, internal)
• LICENSE - MIT license file

MIT