Esvg

Easly slip optimized, cached svgs into your workflow using standalone CLI or the simple Rails integration.

  1. Converts a directory full of SVGs into a an optimized SVG using symbols for each file.
  2. Build a Javascript file to inject SVGs into pages, so it's easily cacheable.
  3. Offers Rails application helpers for placing icons in your views.

Gem Version Build Status License

Installation

Add this line to your application's Gemfile:

gem 'esvg'

And then execute:

$ bundle

Or install it yourself as:

$ gem install esvg

Usage: Rails

Add Esvg.precompile_assets to your config/initializers/assets.rb to add build with rake assets:precomile.

Add SVG files to your app/assets/svgs/ directory.

for example:

app/assets/svgs
 - .svg
 - share.svg
 - thumbs-up.svg

Inject SVG symbols

Add this to a page or layout where SVGs should be available

<%= embed_svgs %>

During development:

This will embed a <script> which will place svg symbols at the top of your site's <body> as soon as the DOM is ready, and after any Turbolinks page load events.

In Production:

The embed_svgs view helper will write a javascript_include_tag to include the script (rather than embeding it in the page). When you run rake assets:precompile this script will be built to public/assets/svgs-{fingerprint}.js (and a gzipped version).

This allows browsers to cache the javascript files and reduce the weight of downloading svgs for each page.

Placing an SVG

To place an SVG, use the use_svg vew helper. This helper will embed an SVG use tag which will reference the appropriate symbol. Here's how it works.

# Syntax: use_svg name, [options]

# Standard example
<%= use_svg 'logo' %>

# Output:
# <svg class="svg-symbol svg-logo"><use xlink:href="#svg-logo"/></svg>

# Add custom classnames
<%= use_svg 'share', class: 'disabled' %>

# Output: 
# <svg class="svg-symbol svg-share disabled"><use xlink:href="#svg-share"/></svg>

# Add custom styles
<%= use_svg 'logo', style: 'fill: #c0ffee' %>

# Output: 
# <svg class="svg-symbol svg-logo" style="fill: #coffee;"><use xlink:href="#svg-logo"/></svg>

# Add title and desc tags for SVG accessibility.
<%= use_svg 'kitten', title: "Mr. Snuggles", desc: "A graphic of a cat snuggling a ball of yarn" %>

# Output: 
# <svg class="icon kitten-icon"><use xlink:href="#kitten-icon"/>
#   <title>Mr. Snuggles</title>
#   <desc>A graphic of a cat snuggling a ball of yarn</desc>
# </svg>

# Provide fallback icon if an icon is missing (great for when you are generating icon names from code)
<%= use_svg 'missing', fallback: 'default' %>

Usage: stand-alone CLI

# Syntax:
$ esvg PATH [options]

# Examples:
$ esvg                      # Read icons from current directory, write js to ./svgs.js
$ esvg icons                # Read icons from 'icons' directory, write js to ./svgs.js
$ esvg --output build       # Read icons from current directory, write js to build/svgs.js
$ esvg -c --config foo.yml  # Read confguration from foo.yml (otherwise, defaults to esvg.yml, or config/esvg.yml)

Configuration

If you're using esvg from the command line, configuration files are read from ./esvg.yml or you can pass a path with the --config option to read the config file from elsewhere.

source: .                   # Where to find SVG icons (Rails defaults to app/assets/esvg)
build: .                    # Where to write build files
assets: .                   # Where to write asset files (builds for directories beginning in _)
tmp: .                      # Write temporary cache files (will write to #{dir}/.esvg-cache/

class: svg-symbol           # All svgs with `use_svg` will have this base classname
namespace: svg              # Namespace for symbol ids, e.g 'svg-logo'
namespace_before: true      # Add namespace before, e.g. 'svg-logo', false would be 'logo-svg'

alias:                      # Add aliases for icon names
  comment: chat             # use "chat" to reference comment.svg
  error: bad, broken        # Use "bad" or "broken" to reference error.svg

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/imathis/esvg. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.