# Esvg Easily embed optimized SVGs in JS, HTML, or CSS. Use as a standalone tool or with Rails. 1. Converts a directory full of SVGs into a single optimized SVG using symbols. 2. Uses Javascript to inject SVGs into pages, so it's easily cacheable. 3. Offers Rails application helpers for placing icons in your views. [](https://rubygems.org/gems/esvg) [](https://travis-ci.org/imathis/esvg) [](http://imathis.mit-license.org) ## Installation Add this line to your application's Gemfile: ```ruby gem 'esvg' ``` And then execute: $ bundle Or install it yourself as: $ gem install esvg ## Usage: Rails First, add SVG files to your `app/assets/esvg/` directory. ### Inject SVG symbols Then create an `esvg.js.erb` in your `app/assets/javascripts/` and add the following: ``` <%= Esvg.embed %> ``` Finally add the following to your `application.js` ``` //= require esvg ``` This script will inject your SVG symbols at the top of your site's `<body>` as soon as the DOM is ready, and after any Turbolinks `page:change` event. ### Place an icon To place an SVG icon, use the `svg_icon` helper. This helper will embed an SVG `use` tag which will reference the appropriate symbol. Here's how it works. ``` # Syntax: svg_icon name, [options] # Standard example <%= svg_icon 'kitten' %> # Output: # <svg class="icon kitten-icon"><use xlink:href="#kitten-icon"/></svg> # Add custom classnames <%= svg_icon 'kitten', class: 'adorbs' %> # Output: # <svg class="icon kitten-icon adorbs"><use xlink:href="#kitten-icon"/></svg> # Provide fallback icon if an icon is missing <%= svg_icon 'missing', fallback: 'kitten' %> # Output: # <svg class="icon kitten-icon"><use xlink:href="#kitten-icon"/></svg> # Add custom styles <%= svg_icon 'kitten', style: 'color: #c0ffee' %> # Output: # <svg class="icon kitten-icon" style="color: #coffee;"><use xlink:href="#kitten-icon"/></svg> # Add title and desc tags for SVG accessibility. <%= svg_icon '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> ``` ## Usage: stand-alone CLI ``` # Syntax: $ esvg PATH [options] # Examples: $ esvg # Read icons from current directory, write js to ./esvg.js $ esvg icons # Read icons from 'icons' directory, write js to ./esvg.js $ esvg --output embedded # Read icons from current directory, write js to embedded/esvg.js $ esvg -f --format # Embed icons in Stylesheet and write to ./esvg.scss $ 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. ``` path: . # Where to find SVG icons (Rails defaults to app/assets/esvg) output_path: . # Where to write output files (CLI only) format: js # Format for output (js, html, css) base_class: svg-icon # Select all icons with this base classname namespace: icon # Namespace for symbol ids or CSS classnames namespace_before: true # Add namespace before, e.g. icon-kitten 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 font_size: 1em # Default size for SVGs (if embeded in stylesheets) ``` ## 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](contributor-covenant.org) code of conduct. ## License The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).