svg_sprite
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.