Transform SVGs into React components 🦁
Watch the talk at React Europe
npx @svgr/cli
Supporting SVGR
SVGR is an MIT-licensed open source project. It's an independent project with ongoing development made possible thanks to the support of these awesome backers. If you'd like to join them, please consider:
Gold Sponsors
Gold Sponsors are those who have pledged $200/month and more to SVGR.
Example
Take an icon.svg:
<?xml version="1.0" encoding="UTF-8"?>
<svg
width="48px"
height="1px"
viewBox="0 0 48 1"
version="1.1"
xmlns="http://www.w3.org/2000/svg"
xmlns:xlink="http://www.w3.org/1999/xlink"
>
<!-- Generator: Sketch 46.2 (44496) - http://www.bohemiancoding.com/sketch -->
<title>Rectangle 5</title>
<desc>Created with Sketch.</desc>
<defs></defs>
<g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
<g
id="19-Separator"
transform="translate(-129.000000, -156.000000)"
fill="#063855"
>
<g id="Controls/Settings" transform="translate(80.000000, 0.000000)">
<g id="Content" transform="translate(0.000000, 64.000000)">
<g id="Group" transform="translate(24.000000, 56.000000)">
<g id="Group-2">
<rect id="Rectangle-5" x="25" y="36" width="48" height="1"></rect>
</g>
</g>
</g>
</g>
</g>
</g>
</svg>
Run SVGR
npx @svgr/cli --icon --replace-attr-values "#063855=currentColor" icon.svg
Output
import React from 'react'
const SvgComponent = props => (
<svg width="1em" height="1em" viewBox="0 0 48 1" {...props}>
<path d="M0 0h48v1H0z" fill="currentColor" fillRule="evenodd" />
</svg>
)
export default SvgComponent
Motivation
React supports SVG out of the box, it's simpler, easier and much more powerful to have components instead of SVG files. Wrapped in a React component, your SVG is inlined in the page and you can style it using CSS.
SVGR differs from other library by its solid architecture. It uses rehype + Babel to transform SVG code into JavaScript code.
SVGR is included in create-react-app v2 and gives you the power to import SVG directly as a React component.
Command line usage
Usage: svgr [options] <file|directory>
Options:
-V, --version output the version number
--config-file <file> specify the path of the svgr config
--no-runtime-config disable runtime config (".svgrrc", ".svgo.yml", ".prettierrc")
-d, --out-dir <dirname> output files into a directory
--ext <ext> specify a custom file extension (default: "js")
--filename-case <case> specify filename case ("pascal", "kebab", "camel") (default: "pascal")
--icon use "1em" as width and height
--native add react-native support with react-native-svg
--ref forward ref to SVG root element
--no-dimensions remove width and height from root SVG tag
--expand-props [position] disable props expanding ("start", "end", "none") (default: "end")
--svg-props <property=value> add props to the svg element
--replace-attr-values <old=new> replace an attribute value
--template <file> specify a custom template to use
--title-prop create a title element linked with props
--prettier-config <fileOrJson> Prettier config
--no-prettier disable Prettier
--svgo-config <fileOrJson> SVGO config
--no-svgo disable SVGO
-h, --help output usage information
Examples:
svgr --replace-attr-values "#fff=currentColor" icon.svg
Recipes
Transform a whole directory
A whole directory can be processed, all SVG files (matching .svg
or .SVG
)
are transformed into React components.
# Usage: npx @svgr/cli [-d out-dir] [src-dir]
$ npx @svgr/cli -d icons icons
icons/web/clock-icon.svg -> icons/web/ClockIcon.js
icons/web/wifi-icon.svg -> icons/web/WifiIcon.js
icons/spinner/cog-icon.svg -> icons/spinner/CogIcon.js
icons/spinner/spinner-icon.svg -> icons/spinner/SpinnerIcon.js
Use stdin
$ npx @svgr/cli < icons/web/wifi-icon.svg
Use stdin / stdout
$ npx @svgr/cli < icons/web/wifi-icon.svg > icons/web/WifiIcon.js
Transform icons
To create icons, two options are important:
-
--icon
: viewBox is preserved and SVG inherits text size -
--replace-attr-values "#000000=currentColor"
: "#000000" is replaced by "currentColor" and SVG inherits text color
$ npx @svgr/cli --icon --replace-attr-values "#000000=currentColor" my-icon.svg
Target React Native
It is possible to target React Native using react-native-svg.
$ npx @svgr/cli --native my-icon.svg
Use a specific template
You can use a specific template.
$ npx @svgr/cli --template path/to/template.js my-icon.svg
An example of template:
function template(
{ template },
opts,
{ imports, componentName, props, jsx, exports },
) {
return template.ast`
${imports}
const ${componentName} = (${props}) => ${jsx}
${exports}
`
}
module.exports = template
Template must return a Babel AST, the template function takes three arguments:
-
api
: API methods provided by Babel -
opts
: SVGR options -
values
: Pre-computed values to use (or not) in your templates
Usage with Jest
If you use @svgr/webpack
, importing .svg
files in Jest could break your code. To avoid that, add moduleNameMapper
in your Jest configuration.
// __mocks__/svgMock.js
module.exports = 'SvgMock'
module.exports.ReactComponent = 'SvgMock'
// jest.config.js
module.exports = {
moduleNameMapper: {
'\\.svg': '<rootDir>/__mocks__/svgMock.js',
},
}
Node API usage
Webpack loader
Rollup plugin
Apply advanced transformations using Babel
Configurations
SVGR
SVGR uses cosmiconfig for configuration file support. This means you can configure SVGR via:
- A
.svgrrc
file, written in YAML or JSON, with optional extensions: .yaml/.yml/.json/.js. - A
svgr.config.js
file that exports an object. - A "svgr" key in your package.json file.
The configuration file will be resolved starting from the location of the file being formatted, and searching up the file tree until a config file is (or isn't) found.
The options to the configuration file are the same as the API options.
Example
JSON:
{
"icon": true,
"expandProps": false
}
JS:
// .svgrrc.js
module.exports = {
icon: true,
expandProps: false,
}
YAML:
# .svgrrc
icon: true
expandProps: false
Prettier
The recommended way to configure Prettier for SVGR is to use .prettierrc
. It is fully supported in all formats available and it is relative to the transformed SVG file.
Even if it is not recommended, you can also use prettierConfig
option to specify your Prettier configuration. prettierConfig
has precedence on .prettierrc
.
SVGO
The recommended way to configure SVGO for SVGR is to use .svgo.yml
. Several formats are suported and it is relative to the transformed SVG file.
Even if it is not recommended, you can also use svgoConfig
option to specify your SVGO configuration. svgoConfig
has precedence on .svgo.yml
.
Options
SVGR ships with a handful of customizable options, usable in both the CLI and API.
Config file
Specify a custom config file.
Default | CLI Override | API Override |
---|---|---|
null |
--config-file |
configFile: <string> |
Runtime config
Disable runtime config (.svgrrc
, .svgo.yml
, .prettierrc
).
Default | CLI Override | API Override |
---|---|---|
null |
--config-file |
configFile: <string> |
File extension
Specify a custom extension for generated files.
Default | CLI Override | API Override |
---|---|---|
"js" |
--ext |
ext: <string> |
Icon
Replace SVG "width" and "height" value by "1em" in order to make SVG size inherits from text size.
Default | CLI Override | API Override |
---|---|---|
false |
--icon |
icon: <bool> |
Native
Modify all SVG nodes with uppercase and use a specific template with
react-native-svg
imports. All unsupported nodes will be removed.
Default | CLI Override | API Override |
---|---|---|
false |
--native |
native: <bool> |
Dimensions
Remove width and height from root SVG tag.
Default | CLI Override | API Override |
---|---|---|
false |
--no-dimensions |
dimensions: <bool> |
Expand props
All properties given to component will be forwarded on SVG tag. Possible values: "start"
, "end"
or false
.
Default | CLI Override | API Override |
---|---|---|
end |
--expand-props |
expandProps: <string> |
Prettier
Use Prettier to format JavaScript code output.
Default | CLI Override | API Override |
---|---|---|
true |
--no-prettier |
prettier: <bool> |
Prettier config
Specify Prettier config. See Prettier options.
Default | CLI Override | API Override |
---|---|---|
null |
--prettier-config |
prettierConfig: <object> |
SVGO
Use SVGO to optimize SVG code before transforming it into a component.
Default | CLI Override | API Override |
---|---|---|
true |
--no-svgo |
svgo: <bool> |
SVGO config
Specify SVGO config. See SVGO options.
Default | CLI Override | API Override |
---|---|---|
null |
--svgo-config |
svgoConfig: <object> |
Ref
Setting this to true
will forward ref to the root SVG tag.
Default | CLI Override | API Override |
---|---|---|
false |
--ref |
ref: <bool> |
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.
Default | CLI Override | API Override |
---|---|---|
[] |
--replace-attr-values <old=new> |
replaceAttrValues: { old: 'new' }> |
You can specify dynamic property using curly braces:
{ '#000': "{props.color}" }
or--replace-attr-values #000={props.color}
. It is particulary useful with a custom template.
SVG props
Add props to the root SVG tag.
Default | CLI Override | API Override |
---|---|---|
[] |
--svg-props <name=value> |
svgProps: { name: 'value' }> |
You can specify dynamic property using curly braces:
{ focusable: "{true}" }
or--svg-props focusable={true}
. It is particulary useful with a custom template.
Template
Specify a template file (CLI) or a template function (API) to use. For an example of template, see the default one.
Default | CLI Override | API Override |
---|---|---|
basic template |
--template |
template: <func> |
Output Directory
Output files into a directory.
Default | CLI Override | API Override |
---|---|---|
undefined |
--out-dir <dirname> |
Only available in CLI |
License
MIT