svgeez

A Ruby gem for automatically generating an SVG sprite from a folder of SVG icons.

If you're using an SVG icon system in your Web projects, svgeez can help speed up your workflow by automating the SVG sprite generation process. Run svgeez alongside your existing project (or integrate it into your current build system); add, edit, or delete SVG files from a folder; and marvel as svgeez generates a single SVG sprite file ready for inclusion in your user interface.

For more on why SVG sprites are the bee's knees as far as icon systems go, give Chris Coyier's original post, Icon System with SVG Sprites, and his follow-up article, SVG `symbol` a Good Choice for Icons a read-through.

Key Features

• Provides a CLI for generating SVG sprite files.
• Integrates with existing projects (e.g. alongside a Rails application using Foreman).
• Optionally optimizes SVG sprite file with SVGO.

Getting Started

Before installing and using svgeez, you'll want to have Ruby 3.0 (or newer) installed. Using a Ruby version managment tool like rbenv, chruby, or rvm is recommended.

svgeez is developed using Ruby 3.0.6 and is tested against additional Ruby versions using GitHub Actions.

Installation

Add svgeez to your project's Gemfile and run bundle install:

source "https://rubygems.org"

gem "svgeez"

You may also install svgeez directly for use as a standalone tool:

gem install svgeez

Usage

svgeez is a command line program with several useful subcommands. From the root of your project, run svgeez -h for a complete list of commands.

The build command

You can manually generate an SVG sprite from a folder of SVGs with the build command which takes two options, a path to your folder of individual SVGs and a path to the desired destination folder. These paths must be different!

A basic example:

svgeez build --source ~/Sites/sixtwothree.org/images/icons --destination ~/Sites/sixtwothree.org/images/icons.svg

The above example will combine all SVG files in ~/Sites/sixtwothree.org/images/icons into a single SVG sprite file (icons.svg) in ~/Sites/sixtwothree.org/images.

Options and Defaults

Option	Description
-s, --source	Path to folder of source SVGs (defaults to ./_svgeez).
-d, --destination	Path to destination file or folder (defaults to ./svgeez.svg)
-p, --prefix	Optional prefix to append to generated id attribute values
--with-svgo	Optimize SVG sprite file with SVGO

The watch command

The watch command takes the same arguments as the build command but uses the Listen gem to observe changes in the source folder.

Tweaking the example from above:

svgeez watch --source ~/Sites/sixtwothree.org/images/icons --destination ~/Sites/sixtwothree.org/images/icons.svg

svgeez will remaing running, watching for new, removed, or updated SVG files in the provided source folder. As SVG files are added, deleted, or modified in the source folder, svgeez will pump out updated SVG sprite files to the destination folder.

Preparing SVG files for svgeez

svgeez works best with well-organized SVG files. If you're using tools like Sketch or Adobe Illustrator, your source SVG files may contain unnecessary cruft like comments and editor-specific attributes. svgeez will do its best to work with source SVG files, but as a general rule it's good practice to make sure that the SVG files exported from your editor are as concise as possible.

The first section of Jayden Seric's post, How to optimize SVG, offers some helpful advice on optimizing SVGs prior to exporting from editing software.

Optimizing generated files with SVGO

If you have the excellent SVGO utility installed on your system (and the svgo command is available in your PATH), you can use the --with-svgo option and optimize the generated sprite file.

Note: If using SVGO with svgeez, you must use SVGO version 1.3.2. Future releases of svgeez will update to use SVGO version 2.x.x.

svgeez build --source ~/Sites/sixtwothree.org/images/icons --destination ~/Sites/sixtwothree.org/images/icons.svg --with-svgo

Depending on the number of individual SVG files in the source folder, using the --with-svgo option can add considerable time to SVG sprite generation.

Working with SVG sprites

Within generated SVG sprite files, each icon is wrapped in a <symbol> element and assigned an id attribute with a value combining the SVG sprite's file name and the original, individual icon's file name.

For example, a file named menu.svg in ~/Sites/sixtwothree.org/images/icons will be assigned an id value of icons-menu.

<symbol id="icons-menu" viewBox="0 0 32 32">
  <path d="…"/>
</symbol>

Note: Single quotes, double quotes, and spaces in individual icon file names will be replaced with dashes. This could result in two <symbol>s with the same id attribute value. Keep this in mind when naming your source icon files.

Markup

To use an svgeez-generated SVG sprite file, first include the file's contents at the bottom of your HTML page.

In a Rails 4.1.x or lower application:

<body>
  <!-- Your page’s awesome content goes here! -->

  <%= raw Rails.application.assets.find_asset('icons.svg') %>
</body>

In a Rails 4.2.x or 5 application:

<body>
  <!-- Your page’s awesome content goes here! -->

  <%= raw Rails.application.assets_manifest.find_sources('icons.svg').first %>
</body>

In a Rails 7 application with Propshaft:

<body>
  <!-- Your page’s awesome content goes here! -->

  <%= raw Rails.application.assets.load_path.find('icons.svg').content %>
</body>

Or, with PHP:

<body>
  <!-- Your page’s awesome content goes here! -->

  <?php include_once('path/to/icons.svg'); ?>
</body>

Next, wherever you want to include an icon in your user interface, use HTML similar to the following, replacing the identifier #icons-menu with a value corresponding to the ID of the <symbol> in the relevant SVG sprite file:

<svg><use xlink:href="#icons-menu"></svg>

A more complete example from a Rails 4.1.x or lower application's layout file:

<body>
  <button>
    <svg><use xlink:href="#icons-menu"></svg>
    Menu
  </button>

  <%= raw Rails.application.assets.find_asset('icons.svg') %>
</body>

A more complete example from a Rails 4.2.x or 5 application's layout file:

<body>
  <button>
    <svg><use xlink:href="#icons-menu"></svg>
    Menu
  </button>

  <%= raw Rails.application.assets_manifest.find_sources('icons.svg').first %>
</body>

In this example, the contents of the svgeez-generated SVG sprite file is included on every page and isn't terribly cacheable. How onerous this is depends on the size of your icon system.

For smaller icon sets, this may be an acceptable balance of user and developer needs. For larger icon sets, you may want to investigate more advanced techniques for loading and caching an SVG sprite file (perhaps with localStorage…?)

Styling embedded icons

Icons embedded with the inline <use> technique will inherit their fill color from the nearest parent's color value, but this can be overriden with CSS:

button {
  color: #333;
}

button svg {
  fill: #c00; // Absent this declaration, the icon’s fill color would be #333
}

Acknowledgments

svgeez benefited greatly from the hard work done by the folks working on the following projects:

• Jekyll
• jekyll-watch
• Mercenary
• Listen

Additionally, Chris Coyier's CSS Tricks posts linked above got me interested in SVG sprites.

Lastly, the sample icons in spec/fixtures/icons are from Brent Jackson's Geomicons Open icon set.

svgeez is written and maintained by Jason Garber.

Additional Contributors

• Abhinav Mishra
• Brett Wilkins
• danny
• Denis Hovart
• Desmond Sadler
• motoroller95

License

svgeez is freely available under the MIT License. Use it, learn from it, fork it, improve it, change it, tailor it to your needs.