# svgeez
**A Ruby gem for automatically generating an SVG sprite from a folder of SVG icons.**
[](https://rubygems.org/gems/svgeez)
[](https://rubygems.org/gems/svgeez)
[](https://travis-ci.org/jgarber623/svgeez)
[](https://codeclimate.com/github/jgarber623/svgeez)
[](https://codeclimate.com/github/jgarber623/svgeez/coverage)
If you're using an [SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) 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](https://css-tricks.com/svg-sprites-use-better-icon-fonts/), and his follow-up article, [SVG \`symbol\` a Good Choice for Icons](https://css-tricks.com/svg-symbol-good-choice-icons/) a read-through._
## Key Features
- Provides a [CLI](https://en.wikipedia.org/wiki/Command-line_interface) for generating SVG sprite files.
- Integrates with existing projects (e.g. alongside a Rails application using [Foreman](https://github.com/ddollar/foreman)).
- Optionally optimizes SVG files with [SVGO](https://github.com/svg/svgo/).
## Getting Started
Before installing and using svgeez, you'll want to have Ruby 2.2.6 (or newer) installed on your computer. There are plenty of ways to go about this, but my preference is [rbenv](https://github.com/sstephenson/rbenv). If you're developing on a Mac and using [Homebrew](http://brew.sh/), installing rbenv is [super easy](https://github.com/sstephenson/rbenv#homebrew-on-mac-os-x).
svgeez _might_ work with other versions of Ruby, but it's developed in 2.2.6 and automatically tested against 2.3.4 and 2.4.1 by [Travis CI](https://travis-ci.org/jgarber623/svgeez).
## Installation
If you're using Bundler, add svgeez to your project's Gemfile:
```rb
ruby '2.2.6'
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:
```sh
$ 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](https://github.com/svg/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](https://github.com/guard/listen) to observe changes in the source folder.
Tweaking the example from above:
```sh
$ 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](http://jaydenseric.com/blog/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](https://github.com/svg/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.
```sh
$ 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 `` 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`.
```svg
```
**Note:** Single quotes, double quotes, and spaces in individual icon file names will be replaced with dashes. This _could_ result in two ``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:
```erb
<%= raw Rails.application.assets.find_asset('icons.svg') %>
```
In a Rails 4.2.x or 5 application:
```erb
<%= raw Rails.application.assets_manifest.find_sources('icons.svg').first %>
```
Or, with PHP:
```html
```
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 `` in the relevant SVG sprite file:
```html
```
A more complete example from a Rails 4.1.x or lower application's layout file:
```erb
<%= raw Rails.application.assets.find_asset('icons.svg') %>
```
A more complete example from a Rails 4.2.x or 5 application's layout file:
```erb
<%= raw Rails.application.assets_manifest.find_sources('icons.svg').first %>
```
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](https://developer.mozilla.org/en-US/docs/Web/API/Storage/LocalStorage)…?)
### Styling embedded icons
Icons embedded with the inline `