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. Simply 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 simple CLI for generating SVG sprite files.
Easily integrates with existing projects (e.g. alongside a Rails application using Foreman).
Optionally optimizes SVG files with SVGO.

Getting Started

Before installing and using svgeez, you'll want to have Ruby 2.2.5 installed on your computer. There are plenty of ways to go about this, but my preference is rbenv. If you're developing on a Mac and using Homebrew, installing rbenv is super easy.

svgeez might work with other versions of Ruby, but it's developed in 2.2.5.

Installation

If you're using Bundler, add svgeez to your project's Gemfile:

ruby '2.2.5'

source 'https://rubygems.org' do
  gem 'svgeez'
end

…and hop over to your command prompt and run…

$ bundle

You may also install svgeez directly by issuing the following command:

$ 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 the folder of source SVGs (defaults to `./_svgeez`).
`-d` `--destination`	Path to the destination file or folder (defaults to `./svgeez.svg`)
`--with-svgo`	Optimize source SVGs with SVGO before sprite generation (non-destructive)

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 keep pumping out updated SVG sprite files to the destination folder.

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 source SVGs before generating the sprite file.

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

Optimizing source SVG files with SVGO is done on-the-fly and the original files are left intact. 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 application:

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

    <%= raw Rails.application.assets.find_asset('icons.svg') %>
</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 application's layout file:

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

    <%= raw Rails.application.assets.find_asset('icons.svg') %>
</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
}

Improving svgeez

You want to help make svgeez better? Hell yeah! I like your enthusiasm. For more on how you can help, check out CONTRIBUTING.md.

Donations

If diving into Ruby isn't your thing, but you'd still like to support svgeez, consider making a donation! Any amount—large or small—is greatly appreciated. As a token of my gratitude, I'll add your name to the Acknowledgments below.

Acknowledgments

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

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

Brett Wilkins

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.

fragkakis/svgeez