Project

svg_sprite

0.0
Low commit activity in last 3 years
No release in over a year
Create SVG sprites using SVG links.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies
 Project Readme

svg_sprite

Tests Gem Gem

Create SVG sprites by embedding images into CSS using data URIs. The SVGs are optimized using svg_optimizer.

Installation

gem install svg_sprite

Or add the following line to your project's Gemfile:

gem "svg_sprite"

Usage

Let's assume there's a directory called images with the following files:

$ tree images
images
├── doc-fill.svg
├── doc.svg
├── trash-fill.svg
└── trash.svg

0 directories, 4 files

The following command will export the SVG sprite and a CSS file with all dimensions.

$ svg_sprite generate --input images \
                      --css-path sprite/icons.css \
                      --sprite-path sprite/icons.svg \
                      --name icon

All SVGs will be combined into one simple file. You can then refer to the SVG by using a link.

<svg>
  <use href="sprite/icons.svg#trash" role="presentation">
</svg>

If you want to restrict the SVG to the original dimensions, use the export CSS file. Classes are defined using the --name name (defaults to sprite), together with the file name. This is an example:

/*
This file was generated by https://rubygems.org/gems/svg_sprite with the
following command:

svg_sprite generate --input images --sprite-path sprite/icons.svg --css-path sprite/icons.css --optimize --name icon
*/

.icon--doc-fill {
  width: 42px;
  height: 52px;
}

.icon--doc {
  width: 42px;
  height: 52px;
}

.icon--trash-fill {
  width: 48px;
  height: 53px;
}

.icon--trash {
  width: 48px;
  height: 54px;
}

By default, SVGs will keep their stroke and fill colors. You can remove or use currentColor instead by using --stroke and --fill.

$ svg_sprite generate --input images \
                      --sprite-path sprite/icons.svg \
                      --css-path sprite/icons.css \
                      --name icon \
                      --stroke current-color \
                      --fill current-color

$ svg_sprite generate --input images \
                      --sprite-path sprite/icons.svg \
                      --css-path sprite/icons.css \
                      --name icon \
                      --stroke remove \
                      --fill remove

Finally, all SVGs will be optimized using svg_optimizer. To disable it, use --no-optimize.

Using sprites in practice

You need to embed the final SVG sprite on your HTML page. With Rails, you can use a helper like this:

module ApplicationHelper
  def svg_tag(file)
    File.open(Rails.root.join("app/assets/images", "#{file}.svg")).html_safe
  end
end

Then, on your layout file (e.g. application.html.erb), you can render it as <%= svg_tag(:icons) %>.

Now, you need to reference those SVG links by adding <use href="#id">. You can create a helper method like this to make things easy.

module ApplicationHelper
  def icon(name)
    content_tag :svg, class: "icon icon--#{name}" do
      content_tag :use, nil, href: "##{name}", role: :presentation
    end
  end
end

You can render icons by using <%= icon(:trash) %>.

Programming API

To export both the CSS and SVG files:

require "svg_sprite"

SvgSprite.call(
  input: "./images/icons",
  name: "icon",
  css_path: "./sprite/icons.css",
  svg_path: "./sprite/icons.svg",
  optimize: true,
  stroke: "remove",
  fill: remove
)

Maintainer

Contributors

Contributing

For more details about how to contribute, please read https://github.com/fnando/svg_sprite/blob/main/CONTRIBUTING.md.

License

The gem is available as open source under the terms of the MIT License. A copy of the license can be found at https://github.com/fnando/svg_sprite/blob/main/LICENSE.md.

Code of Conduct

Everyone interacting in the svg_sprite project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.