SvgLoaderOptions

SVG loader options.

Paths

If an option accepts a path, both file name and the path relative to the project’s root with leading slash are compared against the matchers.

For example, for a file /src/assets/icons/menu.svg following strings will be compared:

/assets/icons/menu.svg - note that it doesn’t start with /src
menu.svg

To avoid transforming multiple files with the same name, always include path into each entry.

Examples:

viteAwesomeSvgLoader({
  preserveLineWidthList: [
    // Recommended formats:
    new RegExp("\\/img\\/icons"), // Matches all paths containing "/img/line-art/"
    "/assets/img/logo.svg", // Matches single file "/assets/img/logo.svg"

    // Not recommended formats:
    "splash.svg", // Matches all files named "splash.svg"
    new RegExp("\\/icons\\/plus\\.svg", // Matches all paths containing "/icons/plus.svg"
  ],
})

Properties

defaultImport?

optional defaultImport: ImportType

Defined in: types.ts:270

Default import type, i.e. what you get without specifying anything in the import URL.

This also can be done in an import:

// Source code
import imageSrc from "./path/to/image.svg?source";

// URL
import imageUrl from "./path/to/image.svg?url";

// Source code Data URI
import imageSrcDataUri from "./path/to/image.svg?source-data-uri";

// Base64
import imageBase64 from "./path/to/image.svg?base-64";

// Base64 data URI
import imageBase64DataUri from "./path/to/image.svg?base-64-data-uri";

Default

"source"

preserveLineWidthList?

optional preserveLineWidthList: (string | RegExp)[]

Defined in: types.ts:53

A list of files or directories to preserve line width of, i.e. to set vector-effect="non-scaling-stroke".

This option is primarily for icons and line art.

This also can be done in an import: import imageSrc from "./path/to/image.svg?preserve-line-width".

Example

viteAwesomeSvgLoader({
  preserveLineWidthList: [new RegExp("some\/pattern\/"), "some/directory", "some/file.svg"],
})

replaceColorsList?

optional replaceColorsList: (string | RegExp | ColorMap | ColorMapPerFiles)[]

Defined in: types.ts:149

A list of files or directories to replace fill, stroke and <stop> colors with currentColor (default) or other colors (if ColorMapPerFiles or ColorMap is specified), i.e.:

fill, stroke and stop-color attributes and CSS identifiers will be replaced with currentColor or other given color.
none, transparent or currentColor values will not be replaced.

Opacity (i.e. rgba()) won’t be preserved. You have to manually set opacity by setting fill-opacity and stroke-opacity attributes.

This is done because opacity may be handled with a stylesheet selector. This case is hard to implement, and it may slow down build process. This behavior might be changed in future, but it shouldn’t break your project.

Setting currentColor can be done with an import: import imageSrc from "./path/to/image.svg?set-current-color".

Replacements priority:

ColorMapPerFiles
ColorMap
string | RegExp

Example

viteAwesomeSvgLoader({
  replaceColorsList: [
    // File names
    "some-file.svg",

    // Regexes that are checked against whole path and file name with extension
    new RegExp("some\/pattern\/"),

    // Map of color replacements. Key is an original color, value is its replacement. Both can be any values:
    // HEX, name, rgb() or arbitrary custom values. Applied to all files.
    {
      "#003147": "red",
      "rgb(0, 49, 71)": "#003147",
      "myCustomColor": "var(--some-color-var)",
    },

    // Map of color replacements per files
    {
      files: ["vars.svg"], // File names or regexes, same format as above

      // Replacements, same format as above
      replacements: {
        red: "var(--primary-color)",
        green: "var(--secondary-color)",
        blue: "var(--tertiary-color)",
      },

      // Default value for colors that are not in replacements map. Set an empty string to preserve original colors.
      // Default value is "currentColor",
      default: "currentColor"
    },
  ],
})

setCurrentColorList?

optional setCurrentColorList: (string | RegExp)[]

Defined in: types.ts:281

A list of files or directories to replace fill, stroke and <stop> colors of with currentColor.

Overrides replaceColorsList.

skipFilesList?

optional skipFilesList: (string | RegExp)[]

Defined in: types.ts:244

A list of files to skip loading of. Files will be passed to another loader.

This also can be done in an import: import imageSrc from "./path/to/image.svg?skip-transforms".

Example

viteAwesomeSvgLoader({
  skipFilesList: [new RegExp("some\/pattern\/"), "some/directory", "some/file.svg"],
})

skipPreserveLineWidthList?

optional skipPreserveLineWidthList: (string | RegExp)[]

Defined in: types.ts:64

A list of files or directories to disable preserving line width of. Overrides preserveLineWidthList.

Example

viteAwesomeSvgLoader({
  skipPreserveLineWidthList: [new RegExp("some\/pattern\/"), "some/directory", "some/file.svg"],
})

skipPreserveLineWidthSelectors?

optional skipPreserveLineWidthSelectors: (string | SelectorsPerFiles)[]

Defined in: types.ts:89

A list of CSS selectors to disable preserveLineWidthList for. Use it to leave specific elements stroke width as-is.

Can be a list of selectors or selectors-per-files specifiers.

Unlike skipSetCurrentColorSelectors and skipTransformsSelectors, doesn’t impact build performance.

Example

viteAwesomeSvgLoader({
  skipPreserveLineWidthSelectors: [
    // It can be a list of CSS selectors like this one. Every element in every file will be checked against it.
    '*[data-original-line-width="true"], *[data-original-line-width="true"] *',

    // Or it can be configured on per-file basis:
    {
      files: [/ignore-elements\.svg/, /some-other-file\.svg/],
      selectors: ['*[data-original-line-width="true"], *[data-original-line-width="true"] *'],
    },
  ],
})

skipReplaceColorsList?

optional skipReplaceColorsList: (string | RegExp)[]

Defined in: types.ts:160

A list of files or directories to disable color replacements of. Overrides replaceColorsList.

Example

viteAwesomeSvgLoader({
  skipReplaceColorsList: [new RegExp("some\/pattern\/"), "some/directory", "some/file.svg"],
})

skipReplaceColorsSelectors?

optional skipReplaceColorsSelectors: (string | SelectorsPerFiles)[]

Defined in: types.ts:188

A list of CSS selectors to disable skipReplaceColorsList for. Use it to leave specific elements colors as-is.

Can be a list of selectors or selectors-per-files specifiers.

You probably don’t need this option. Think of other ways to solve your problem. “Recipes” section in the demos may help you.

Heavy usage may significantly slow down build time. Limit selectors to specific files to improve performance.

Example

viteAwesomeSvgLoader({
  skipReplaceColorsSelectors: [
    // It can be a list of CSS selectors like this one. Every element in every file will be checked against it.
    '*[data-original-colors="true"], *[data-original-colors="true"] *',

    // Or it can be configured on per-file basis:
    {
      files: [/ignore-elements\.svg/, /some-other-file\.svg/],
      selectors: ['*[data-original-colors="true"], *[data-original-colors="true"] *'],
    },
  ],
})

skipSetCurrentColorList?

optional skipSetCurrentColorList: (string | RegExp)[]

Defined in: types.ts:289

A list of files or directories to disable setting current color of. Overrides setCurrentColorList and replaceColorsList.

skipSetCurrentColorSelectors?

optional skipSetCurrentColorSelectors: (string | SelectorsPerFiles)[]

Defined in: types.ts:297

A list of CSS selectors to disable setCurrentColorList for.Overrides setCurrentColorList, replaceColorsList and skipReplaceColorsSelectors.

skipTransformsList?

optional skipTransformsList: (string | RegExp)[]

Defined in: types.ts:204

A list of files to skip while transforming. Applies to any transformation except SVGO.

For example, if you add a directory to preserveLineWidthList and add a file in that directory to this list, line width of added file won’t be preserved.

SVGO is still applied to the added files.

Example

viteAwesomeSvgLoader({
  skipTransformsList: [new RegExp("some\/pattern\/"), "some/directory", "some/file.svg"],
})

skipTransformsSelectors?

optional skipTransformsSelectors: (string | SelectorsPerFiles)[]

Defined in: types.ts:231

A list of CSS selectors to disable all transforms for. Use it to leave specific elements as-is.

Can be a list of selectors or selectors-per-files specifiers.

You probably don’t need this option. Think of other ways to solve your problem. “Recipes” section in the demos may help you.

Heavy usage may significantly slow down build time. Limit selectors to specific files to improve performance.

Example

viteAwesomeSvgLoader({
  skipTransformsSelectors: [
    // It can be a list of CSS selectors like this one. Every element in every file will be checked against it.
    '*[data-no-transforms="true"], *[data-no-transforms="true"] *',

    // Or it can be configured on per-file basis:
    {
      files: [/ignore-elements\.svg/, /some-other-file\.svg/],
      selectors: ['*[data-no-transforms="true"], *[data-no-transforms="true"] *'],
    },
  ],
})

tempDir?

optional tempDir: string

Defined in: types.ts:38

Temporary directory where SVG files will be stored in dev mode.

Default

"temp"

urlImportsInLibraryMode?

optional urlImportsInLibraryMode: UrlImportsInLibraryMode

Defined in: types.ts:325

Should emit SVG files in library mode when SVGs are imported via ?url import type.

Possible values:

source-data-uri - no files will be emitted, and source data URI will be exported (like with ?source-data-uri import type).
base-64-data-uri - no files will be emitted, and base64 data URI will be exported (like with ?base-64-data-uri import type).
emit-files - files will be emitted, and exports like this will be produced:
```
"" + new URL("file-name-[hash].svg", import.meta.url).href
```
Warning: suitable only for internal use because:
1. This may cause issues when your library is consumed. Additional setup from the users will be required.
2. This is not aligned with the default Vite behavior.

Default

"source-data-uri"