vite

@svg-use/vite

A vite plugin, for using SVG images via use[href] references. A thin wrapper around @svg-use/rollup, augmented to work with Vite's dev server.

Quick start

First, install the plugin, and the default React wrapper:

pnpm install --dev @svg-use/vite
pnpm install @svg-use/react

Configure Vite

In your Vite config file (vite.config.js or equivalent):

import { defineConfig } from 'vite';
import svgUse from '@svg-use/vite';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [svgUse()],
  build: {
    assetsInlineLimit: (filePath) => {
      // Do not inline SVG images as base64, because base64 is not a valid target for
      // `use[href]`. If you can think of a more narrow check (such that it
      // only targets assets relevant to `@svg-use`), do let us know!
      return !filePath.endsWith('.svg');
    },
  },
});

Optional: Configure TypeScript

If you are using TypeScript, you can get types for the default config by adding the following in a .d.ts file in your project. For example, you can include this in src/client.d.ts, or any other applicable place.

/// <reference types="@svg-use/vite/client" />

Overriding default types

If you wish to override the default types, add a separate .d.ts file with your types. Then, reference that file in client.d.ts, prior to the built-in types

For example, suppose you have changed the signature of the factory function. Specify your own definitions, such as svg-use-overrides.d.ts:

declare module '*.svg' {
  export const Component: ReturnType<
    typeof import('./path/to/my/factory').myFactoryName
  >;
}

In client.d.ts:

/// <reference types="./svg-use-overrides.d.ts" />
/// <reference types="@svg-use/vite/client" />

Use it in your components

import { Component as Arrow } from './arrow.svg?svgUse';
import { Component as ArrowNoTheme } from './arrow.svg?svgUse&noTheme';

const MyComponent = () => (
  <div>
    <Arrow color="currentColor" />
    <ArrowNoTheme />
  </div>
);

You can also create your own SVG use[href] wrappers, using the other named exports. This is how the default Component factory works under the hood:

import { url, id } from './arrow.svg?svgUse';
import { createThemedExternalSvg } from '@svg-use/react';

export const Arrow = createThemedExternalSvg({ url, id });

Worked example

Consult examples/vite-react for a worked example. You can use this as a playground for understanding the transformations, as well as the different moving parts, isolated from your own application's configuration.

Options

getSvgIdAttribute?

optional getSvgIdAttribute: (info: {filename?: string; existingId?: string;}) => string;

Specifies an id for the referenced <svg>, set as the id attribute on the root. An id is required in order for use[href] to work. A default is provided if this is not defined.

Options shared with @svg-use/core

• getThemeSubstitutions
• componentFactory