See what's launched

The next gen Gatsby is here Performance, developer velocity, and scaling to meet Enterprise needs - See what’s launched

Sign Up for Free
Community Plugin
View plugin on GitHub

gatsby-plugin-svg-sprites npm

⚠️ Breaking change: svg.symbol property was renamed to svg.url in v4.2.0.

⚠️ If you are getting “sprites.[contenthash].svg” URLs in production, please check the ”Known issues” section for possible solutions.

Gatsby plugin to generate SVG sprites from imported files. The sprites are generated using External SVG Sprite.

Installation

npm install gatsby-plugin-svg-sprites

Usage

/* gatsby-config.js */

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-svg-sprites'
      options: {
        /* gatsby-plugin-svg-sprites options here */
      }
    }
  ]
}

JavaScript import

import React from 'react'
import icon from 'images/icon.svg'

export default () => (
  <svg viewBox={icon.viewBox}>
    <use xlinkHref={icon.url}/>
  </svg>
)

CSS

.icon {
  background-image: url('images/icon.svg') no-repeat 0;
}

Options

minifyIds

Type: boolean. Default: process.env.NODE_ENV === 'production'.

Minify symbol ids, enabled if process.env.NODE_ENV === 'production' by default.

pluginOptions

Type: Object. Default: {}.

The pluginOptions parameter is passed to External SVG Sprite plugin.

randomContentHash

Type: boolean. Default: false.

Allow this plugin to replace '[contenthash]' placeholder in the name property with a random hash.

External SVG Sprite options

Any other option passed to gatsby-plugin-svg-sprites will be passed to external-svg-sprite-loader — more info about its options can be found here. By default, this plugin will set the following options:

{
  iconName: '[name]--[hash:base64:5]',
  name: 'sprites.[contenthash].svg'
}

Note: if minifyIds is set to true, iconName will be ignored.

Known issues

There’s an issue that affects some projects, where the underlying loader renders the source content before the plugin processes the path strings — resulting in SVG URLs like “sprites.[contenthash].svg”, and thus 404 responses. There are two ways to circumvent this issue: removing any webpack placeholder from the name option — setting it to something like “sprites.svg”; or setting randomContentHash option to true — it enables this plugin to replace the “[contenthash]” placeholder in the name property with random hashes. If you are using Netlify or another service that implements HTTP ETags for cache invalidation, you can safely use a plain filename like sprites.svg. Otherwise, enabling randomContentHash could be a better choice.

License

The MIT License

© 2022 Gatsby, Inc.