SvgSprite
Create SVG sprites by embedding images into CSS using data URIs. The SVGs are optimized using svg_optimizer.
Installation
$ gem install svg_sprite
Usage
Sass support
To create a sprite:
$ svg_sprite -s images/icons -o styles/_icons.scss -n icons
Let's say the images/icons
directory has a file called user.svg
. The command above will create some mixins and placeholders.
// this variable holds all image names
$icons-names
// this placeholder sets a background image
%icons-user
// this mixin will set the background image on the element's `:before` pseudo-element.
@include icons-before("user");
// this mixin will set the background image on the element's `:after` pseudo-element.
@include icons-after("user");
When using SCSS, the generated stylesheet will have a variable with a list of all images inside the generated sprite, so you can hack own your own on top of that.
@each $image in $icons-names {
.my-class-for-#{$image} {
@extend %icons-#{$image};
}
}
CSS support
To create a sprite:
$ svg_sprite -s images/icons -o styles/_icons.css -n icons
Let's say the images/icons
directory has a file called user.svg
. The command above will create some classes.
// this class will set the background image on the element.
.icons-user
// this class will set the background image on the element's `:before` pseudo-element.
.icons-user-before
// this mixin will set the background image on the element's `:after` pseudo-element.
.icons-user-after
Programming API
To generate the sprite without saving the file:
require "svg_sprite"
rendered_css = SvgSprite.create({
source: "./images/icons",
format: "scss",
name: "icons"
}).render
To save the sprite content to a file:
require "svg_sprite"
rendered_css = SvgSprite.export({
source: "./images/icons",
output: "./styles/_icons.scss",
format: "scss",
name: "icons"
})
Adding new formats
First, register your template renderer. The assigned object should respond to call(source, options)
.
# `source` is SvgSprite::Source, which wraps all SVG files.
# Each item returned by `source` is a SvgSprite::SVG instance.
SvgSprite::TEMPLATES["custom"] = proc do |source, |
content = source.to_a.map(&:name).join("\n")
"/*\nImage names:\n#{content}\n*/"
end
Then you can generate the sprite like the following:
rendered_css = SvgSprite.create({
source: "./examples",
format: "custom",
name: "icons"
}).render
#=> /*
#=> Image names:
#=> blue-square
#=> orange-square
#=> green-square
#=> yellow-square
#=> */
See what's available in SvgSprite::SVG class.
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/fnando/svg_sprite. 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.