Esvg

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

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

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:precompile.

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

for example:

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

Inject SVG symbols

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

<%= embed_svgs %>

XHR page content

If page content is loaded after domready and replaces the content of <body>, you can register an event listener by configuring xhr_event in esvg's configuration file to re-embed icons if they have been removed.

For example in the Rails community, Turbolinks is a popular system for loading page content with XHR. After it has finished its work, it fires a turbolinks:load event. If you're using Turbolinks, you'd set xhr_event as follows.

xhr_event: "turbolinks:load"

Which add an the following event listener to esvg's embed script.

document.addEventListener("turbolinks:load", embed)`

This will trigger the embed script, addding the symbols to the top of the <body> if they were removed in a page transition.

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.

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' %>

# Use presets (setup in config yaml)
<%= use_svg 'chevron', preset: 'icon' %>

# Use size classes (setup in config yaml)
<%= use_svg 'chevron', size: 'small' %>

# 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 using Rails, add a configuration file at config/esvg.yml.

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

presets:                    # Add named presets for setting common options
  icon:                     # Passing option preset: 'icon' will set these defaults
    height: 1em
    class: icon

sizes:                      # Define size classes for easy assignment
  small:                    # size classes override presets
    height: 10px
  medium:
    height: 20px

xhr_event: "turbolinks:load"  # Javascript event name to trigger embedding icons after an xhr page load

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.