Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


Gatsby plugin for creating SVG sprites using External SVG Sprite.


$ npm install gatsby-plugin-svg-sprite-loader


// gatsby-config.js

module.exports = {
  plugins: [
      resolve: `gatsby-plugin-svg-sprite-loader`,
      options: {
        /* External SVG Sprite loader options */
        pluginOptions: {
          /* External SVG Sprite plugin options */



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

The options object is passed directly to External SVG Sprite loader, more info can be found here. To keep consistency, name and iconName default values use the same formats used by Gatsby.js for CSS files.


Default: {}; Type: Object.

The pluginOptions parameter is passed to External SVG Sprite plugin.


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

export default () => (
  <svg viewBox={icon.viewBox}>
    <use xlinkHref={icon.url}/>
.icon {
  background-image: url('images/icon.svg') no-repeat 0;

Updating from v0.1.* to v0.2.*

While v0.1.* uses SVG sprite loader under the hood, v0.2.* uses External SVG Sprite. The new package returns the sprite url using the symbol property, while SVG sprite loader uses url. A patch was created to return the value inside the url property, among with symbol. If the default options were being used in v0.1.*, no difference should be noticed.


The MIT License

© 2023 Gatsby, Inc.