SvgLoaderOptions

Defined in: types.ts:6

vite-awesome-svg-loader options

Properties

defaultImport?

optional defaultImport: ImportType

Defined in: types.ts:245

Default import type when no import query is specified. Available values:

source - SVG source code (default).
url - URL pointing to the file.
source-data-uri - SVG source code encoded in data URI.
base64 - SVG source code encoded in base-64.
base64-data-uri: SVG source code encoded in base-64 data URI.

Default

"source"

preserveLineWidthList?

optional preserveLineWidthList: FileMatchers

Defined in: types.ts:21

Files where line width should be preserved by adding vector-effect="non-scaling-stroke".

See FileMatchers for the available formats.

Alternative: Use import query: import image from "./image.svg?preserve-line-width".

replaceColorsList?

optional replaceColorsList: MaybeArray<FileMatcher | ColorMapPerFiles | ColorMap>

Defined in: types.ts:141

Files where fill, stroke and <stop> colors should be replaced with currentColor (default) or custom colors.

What’s replaced:

fill, stroke and stop-color attributes.
CSS identifiers.

What’s untouched:

none, transparent, and currentColor values.

Available formats in application priority (from highest to lowest):

ColorMapPerFiles - a color to replacement map scoped to the files (see FileMatchers) specified in ColorMapPerFile.files property.
ColorMap - a color to replacement map applied to all files.
FileMatcher - files where all colors should be replaced with currentColor.

If multiple entries match the same file, replacements are merged by following rules:

If two entries replace the same color or have ColorMapPerFiles.default set, the entry with highest priority wins.
If, in previous case, both entries have the same priority, the entry with the lowest index in the original array wins.

Caveats:

Opacity set by initial colors, i.e. rgba() is lost when color is replaced. This is so because opacity retention would:

Still bring confusion because one may rightfully expect that color replacement will completely replace colors and not correct them.
Slow down build process.
Impose high maintenance complexity.

Notes:

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

Setting custom color is not possible with import queries.

Example

viteAwesomeSvgLoader({
  replaceColorsList: [
    // FileMatcher: files where all colors should be replaced with `currentColor`
    "some-file.svg",
    new RegExp("\/some\/directory\/"),
    (ctx) => ctx.relativePath.includes("/some/directory/") || ctx.fullPath.endsWith("-image.svg"),

    // ColorMap: map of color replacements.
    // Key is an original color, value is its replacement.
    {
      "#003147": "red",
      "rgb(0, 49, 71)": "#003147",
      "myCustomColor": "var(--some-color-var)",
    },

    // ColorMapPerFiles: a color to replacement map scoped to the specified files
    {
      // File matchers
      files: ["vars.svg"],

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

      // A default color for unspecified colors
      default: "red",
    },
  ],
})

setCurrentColorList?

optional setCurrentColorList: FileMatchers

Defined in: types.ts:252

skipFilesList?

optional skipFilesList: FileMatchers

Defined in: types.ts:232

Files to bypass. They will be passed to another loader.

See FileMatchers for the available formats.

skipPreserveLineWidthList?

optional skipPreserveLineWidthList: FileMatchers

Defined in: types.ts:31

Files where line width should NOT be preserved.

Takes precedence over preserveLineWidthList and import queries (import image from "./image.svg?preserve-line-width").

See FileMatchers for the available formats.

skipPreserveLineWidthSelectors?

optional skipPreserveLineWidthSelectors: CssSelectors

Defined in: types.ts:57

CSS selectors where line width should NOT be preserved. Use this to keep specific elements’ stroke widths unchanged.

See CssSelectors for the available formats and more configuration options.

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

Example

viteAwesomeSvgLoader({
  skipPreserveLineWidthSelectors: [
    // Global selector:
    '*[data-original-line-width="true"], *[data-original-line-width="true"] *',

    // File-scoped selector:
    {
      files: [new RegExp("\/some\\-file\\.svg"), new RegExp("\/other\\-file\\.svg")],
      selectors: ['*[data-original-line-width="true"], *[data-original-line-width="true"] *'],
    },
  ],
})

skipReplaceColorsList?

optional skipReplaceColorsList: FileMatchers

Defined in: types.ts:151

Files where colors should NOT be replaced.

Takes precedence over replaceColorsList and import queries (import image from "./image.svg?set-current-color").

See FileMatchers for the available formats.

skipReplaceColorsSelectors?

optional skipReplaceColorsSelectors: CssSelectors

Defined in: types.ts:180

CSS selectors where colors should NOT be replaced. Use it to leave specific elements colors unchanged.

See CssSelectors for the available formats and more configuration options.

Warning: Heavy usage can significantly slow down build performance.

Limit selectors to specific files to improve performance.

Oe better, consider alternative approaches such as using color maps. See replaceColorsList, ColorMap, and ColorMapPerFiles) for the details.

Example

viteAwesomeSvgLoader({
  skipReplaceColorsSelectors: [
    // Global selector:
    '*[data-original-colors="true"], *[data-original-colors="true"] *',

    // File-scoped selector:
    {
      files: [new RegExp("\/some\\-file\\.svg"), new RegExp("\/other\\-file\\.svg")],
      selectors: ['*[data-original-colors="true"], *[data-original-colors="true"] *'],
    },
  ],
})

skipSetCurrentColorList?

optional skipSetCurrentColorList: FileMatchers

Defined in: types.ts:257

skipSetCurrentColorSelectors?

optional skipSetCurrentColorSelectors: CssSelectors

Defined in: types.ts:262

skipTransformsList?

optional skipTransformsList: FileMatchers

Defined in: types.ts:192

Files to NOT transform (except SVGO).

See FileMatchers for the available formats.

Takes precedence over replaceColorsList, preserveLineWidthList, and import queries (import image from "./image.svg?set-current-color&preserve-line-width").

Alternative: Use import query: import image from "./image.svg?skip-transforms".

skipTransformsSelectors?

optional skipTransformsSelectors: CssSelectors

Defined in: types.ts:225

CSS selectors which should NOT be transformed. Use this to leave specific elements untouched.

See CssSelectors for the available formats and more configuration options.

Warning: Heavy usage can significantly slow down build performance.

Limit selectors to specific files to improve performance.

Or better, consider following approach:

To avoid color replacement, consider alternative approaches such as using color maps. See replaceColorsList, ColorMap, and ColorMapPerFiles) for the details.
To avoid line width preservation, just use skipPreserveLineWidthSelectors.

Example

viteAwesomeSvgLoader({
  skipTransformsSelectors: [
    // Global selector:
    '*[data-no-transforms="true"], *[data-no-transforms="true"] *',

    // File-scoped selector:
    {
      files: [new RegExp("\/some\\-file\\.svg"), new RegExp("\/other\\-file\\.svg")],
      selectors: ['*[data-no-transforms="true"], *[data-no-transforms="true"] *'],
    },
  ],
})

tempDir?

optional tempDir: string

Defined in: types.ts:12

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

Default

"temp"

urlImportsInLibraryMode?

optional urlImportsInLibraryMode: UrlImportsInLibraryMode

Defined in: types.ts:282

Behavior for ?url imports in library mode. Possible values:

source-data-uri - source data URI will be exported, no files will be emitted.
base-64-data-uri - base64 data URI will be exported, no files will be emitted.
emit-files - files will be emitted, following exports will be produced:
```
"" + new URL("file-name-[hash].svg", import.meta.url).href
```
Warning: May cause issues when your library is consumed. Requires additional configuration from the users. Warning: This behavior is not aligned with the default Vite behavior.

Default

"source-data-uri"