Options

SVGR ships with a handful of customizable options, usable in both the CLI and API.

Config file

Specify a custom config file.

DefaultCLI OverrideAPI Override
null--config-fileconfigFile: string

Runtime config

Disable runtime config (.svgrrc, .svgo.yml, .prettierrc).

DefaultCLI OverrideAPI Override
true--no-runtime-configruntimeConfig: boolean

JSX runtime

Specify a JSX runtime to use.

  • "classic": adds import * as React from 'react' on the top of file
  • "automatic": do not add anything
  • "classic-preact": adds import { h } from 'preact' on the top of file
DefaultCLI OverrideAPI Override
classic--jsx-runtimejsxRuntime: 'classic' | 'automatic' | 'classic-preact'

JSX runtime import source

Specify a custom JSX runtime source to use. Allows to customize the import added at the top of generated file.

Example: jsxRuntimeImport: { source: 'preact', specifiers: ['h'] } for "classic-preact" equivalent.

To use the default import instead of a list of names, you can use defaultSpecifier, for example to use svgr with hyperapp-jsx-pragma, you can specify jsxRuntimeImport: { source: 'hyperapp-jsx-pragma', defaultSpecifier: 'h' } to get an end result of import h from "hyperapp-jsx-pragma";

DefaultCLI OverrideAPI Override
null-jsxRuntimeImport: { source: string, specifiers: string[], defaultSpecifier: string }

Icon

Replace SVG width and height by a custom value. If value is omitted, it uses 1em in order to make SVG size inherits from text size.

DefaultCLI OverrideAPI Override
false--icon [value]icon: boolean | string | number

If you use --icon without any argument, be careful of separating files from arguments using --, ex: svgr --icon -- assets/svg

Native

Modify all SVG nodes with uppercase and use a specific template with react-native-svg imports. All unsupported nodes will be removed.

DefaultCLI OverrideAPI Override
false--nativenative: boolean

TypeScript

Generates .tsx files with TypeScript typings.

DefaultCLI OverrideAPI Override
false--typescripttypescript: boolean

Dimensions

Keep width and height attributes from the root SVG tag.

Removal is guaranteed if dimensions: false, unlike the removeDimensions: true SVGO plugin option which also generates a viewBox from the dimensions if no viewBox is present.

NOTE:

  • Any SVGO processing will occur prior to this removal.
  • When removing dimensions, SVGO will be configured not to remove the viewBox if one is present. You can override this behaviour via your own config.
DefaultCLI OverrideAPI Override
true--no-dimensionsdimensions: boolean

Expand props

All properties given to component will be forwarded on SVG tag. Possible values: "start", "end" or false ("none" in CLI).

DefaultCLI OverrideAPI Override
end--expand-propsexpandProps: string

Prettier

Use Prettier to format JavaScript code output.

DefaultCLI OverrideAPI Override
true--no-prettierprettier: boolean

Prettier config

Specify Prettier config. See Prettier options.

DefaultCLI OverrideAPI Override
null--prettier-configprettierConfig: PrettierConfig

SVGO

Use SVGO to optimize SVG code before transforming it into a component.

NOTE: SVGR implicitly enables the prefixIds SVGO plugin which adds a prefix to values of id and class attributes to reduce the chance of collision issues.

DefaultCLI OverrideAPI Override
true--no-svgosvgo: boolean

SVGO config

Specify SVGO config. See SVGO options.

DefaultCLI OverrideAPI Override
null--svgo-configsvgoConfig: SVGOConfig

Ref

Setting this to true will forward ref to the root SVG tag.

DefaultCLI OverrideAPI Override
false--refref: boolean

Memo

Setting this to true will wrap the exported component in React.memo.

DefaultCLI OverrideAPI Override
false--memomemo: boolean

Replace attribute value

Replace an attribute value by an other. The main usage of this option is to change an icon color to "currentColor" in order to inherit from text color.

DefaultCLI OverrideAPI Override
[]--replace-attr-values <old=new>replaceAttrValues: { [key: string]: string }

You can specify dynamic property using curly braces: { '#000': "{props.color}" } or --replace-attr-values #000={props.color}. It is particularly useful with a custom template.

SVG props

Add props to the root SVG tag.

DefaultCLI OverrideAPI Override
[]--svg-props <name=value>svgProps: { [key: string]: string }

You can specify dynamic property using curly braces: { focusable: "{true}" } or --svg-props focusable={true}. It is particularly useful with a custom template.

Accessibility

SVGs by default have an implicit role="graphics-document". To make SVG content accessible you may want to override the default behavior which can be done via the svgProps override.

For web:

DefaultCLI OverrideAPI Override
[]--svg-props role=imgsvgProps: { role: 'img' }

For native:

DefaultCLI OverrideAPI Override
[]--svg-props accessibilityRole=imagesvgProps: { accessibilityRole: 'image' }

Typically for role=img you will want to add either alt text or aria label/description properties to describe the image when rendering the SVG in your application.

NOTE: On the web once you add role: 'img' some screen-readers will automatically announce any title/text/desc nodes within your SVG.

SVGO can be configured to remove those nodes via the built-in removeDesc and removeTitle plugins if you only want to use aria properties during consumption of the SVGs.

Title

Add title tag via title property. If titleProp is set to true and no title is provided (title={undefined}) at render time, this will fallback to an existing title element in the svg if exists.

DefaultCLI OverrideAPI Override
false--title-proptitleProp: boolean

Description

Add desc tag via desc property. If descProp is set to true and no description is provided (desc={undefined}) at render time, this will fallback to an existing desc element in the svg if exists.

DefaultCLI OverrideAPI Override
false--desc-propdescProp: boolean

Template

Specify a template file (CLI) or a template function (API) to use. For an example of template, see the default one.

DefaultCLI OverrideAPI Override
basic template--templatetemplate: <func>

Output Directory

Output files into a directory.

DefaultCLI OverrideAPI Override
undefined--out-dir <dirname>outDir: string

index.js template

Specify a template function (API) to change default index.js output (when --out-dir is used).

DefaultCLI OverrideAPI Override
basic template--index-templateindexTemplate: files => ''

index.js file

Disable index.js file generation

DefaultCLI OverrideAPI Override
false--no-indexindex: boolean

Ignore existing

When used with --out-dir, it ignores already existing files.

DefaultCLI OverrideAPI Override
false--ignore-existingignoreExisting: boolean

Filename case

Specify a custom filename case. Possible values: pascal for PascalCase, kebab for kebab-case, camel for camelCase, or snake for snake_case.

DefaultCLI OverrideAPI Override
pascal--filename-casefilenameCase: string

File extension

Specify a custom extension for generated files.

DefaultCLI OverrideAPI Override
"js"--extext: string
Edit this page on GitHub