inline_svg

by jamesmartin

jamesmartin /inline_svg

Embed SVG documents in your Rails views and style them with CSS

453 Stars 55 Forks Last release: 6 months ago (v1.7.1) MIT License 390 Commits 39 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Inline SVG

Unit tests Integration Tests

Styling a SVG document with CSS for use on the web is most reliably achieved by adding classes to the document and embedding it inline in the HTML.

This gem adds Rails helper methods (

inline_svg_tag
and
inline_svg_pack_tag
) that read an SVG document (via Sprockets or Webpacker, so works with the Rails Asset Pipeline), applies a CSS class attribute to the root of the document and then embeds it into a view.

Inline SVG supports:

Changelog

This project adheres to Semantic Versioning. All notable changes are documented in the CHANGELOG.

Installation

Add this line to your application's Gemfile:

gem 'inline_svg'

And then execute:

$ bundle

Or install it yourself as:

$ gem install inline_svg

Usage

# Sprockets
inline_svg_tag(file_name, options={})

Webpacker

inline_svg_pack_tag(file_name, options={})

Note: The remainder of this README uses `inlinesvgtag

for examples, but the exact same principles work for
inlinesvgpacktag`._

The

file_name
can be a full path to a file, the file's basename or an
IO
object. The actual path of the file on disk is resolved using Sprockets (when available), a naive file finder (
/public/assets/...
) or in the case of
IO
objects the SVG data is read from the object. This means you can pre-process and fingerprint your SVG files like other Rails assets, or choose to find SVG data yourself.

Here's an example of embedding an SVG document and applying a 'class' attribute:

<title>Embedded SVG Documents<title>

Embedded SVG Documents

</div>

Here's some CSS to target the SVG, resize it and turn it an attractive shade of blue:

.some-class {
  display: block;
  margin: 0 auto;
  fill: #3498db;
  width: 5em;
  height: 5em;
}

Options

key

description

id
| set a ID attribute on the SVG
class
| set a CSS class attribute on the SVG
style
| set a CSS style attribute on the SVG
data
| add data attributes to the SVG (supply as a hash)
size
| set width and height attributes on the SVG
Can also be set using
height
and/or
width
attributes, which take precedence over
size

Supplied as "{Width} * {Height}" or "{Number}", so "30px*45px" becomes
width="30px"
and
height="45px"
, and "50%" becomes
width="50%"
and
height="50%"
title
| add a <title> node inside the top level of the SVG document
desc
| add a <desc> node inside the top level of the SVG document
nocomment
| remove comment tags from the SVG document
preserve_aspect_ratio
| adds a
preserveAspectRatio
attribute to the SVG
aria
| adds common accessibility attributes to the SVG (see PR #34 for details)
aria_hidden
| adds the
aria-hidden=true
attribute to the SVG
fallback
| set fallback SVG document

Example:

inline_svg_tag(
  "some-document.svg",
  id: 'some-id',
  class: 'some-class',
  data: {some: "value"},
  size: '30% * 20%',
  title: 'Some Title',
  desc: 'Some description',
  nocomment: true,
  preserve_aspect_ratio: 'xMaxYMax meet',
  aria: true,
  aria_hidden: true,
  fallback: 'fallback-document.svg'
)

Accessibility

Use the

aria: true
option to make
inline_svg_tag
add the following accessibility (a11y) attributes to your embedded SVG:
  • Adds a
    role="img"
    attribute to the root SVG element
  • Adds a
    aria-labelled-by="title-id desc-id"
    attribute to the root SVG element, if the document contains
     or 
     elements

Here's an example:

  An SVG
  This is my SVG. There are many like it. You get the picture

Note: The title and desc

id
attributes generated for, and referenced by,
aria-labelled-by
are one-way digests based on the value of the title and desc elements and an optional "salt" value using the SHA1 algorithm. This reduces the chance of
inline_svg_tag
embedding elements inside the SVG with
id
attributes that clash with other elements elsewhere on the page.

Custom Transformations

The transformation behavior of

inline_svg_tag
can be customized by creating custom transformation classes.

For example, inherit from

InlineSvg::CustomTransformation
and implement the
#transform
method:
# Sets the `custom` attribute on the root SVG element to supplied value
# Remember to return a document, as this will be passed along the transformation chain

class MyCustomTransform < InlineSvg::CustomTransformation def transform(doc) with_svg(doc) do |svg| svg["custom"] = value end end end

Add the custom configuration in an initializer (E.g.

./config/initializers/inline_svg.rb
):
# Note that the named `attribute` will be used to pass a value to your custom transform
InlineSvg.configure do |config|
  config.add_custom_transformation(attribute: :my_custom_attribute, transform: MyCustomTransform)
end

The custom transformation can then be called like so:

haml
%div
  = inline_svg_tag "some-document.svg", my_custom_attribute: 'some value'

In this example, the following transformation would be applied to a SVG document:

...

You can also provide a default_value to the custom transformation, so even if you don't pass a value it will be triggered

# Note that the named `attribute` will be used to pass a value to your custom transform
InlineSvg.configure do |config|
  config.add_custom_transformation(attribute: :my_custom_attribute, transform: MyCustomTransform, default_value: 'default value')
end

The custom transformation will be triggered even if you don't pass any attribute value

haml
%div
  = inline_svg_tag "some-document.svg"
  = inline_svg_tag "some-document.svg", my_custom_attribute: 'some value'

In this example, the following transformation would be applied to a SVG document:

...

And

...

Passing a

priority
option with your custom transformation allows you to control the order that transformations are applied to the SVG document:
InlineSvg.configure do |config|
  config.add_custom_transformation(attribute: :custom_one, transform: MyCustomTransform, priority: 1)
  config.add_custom_transformation(attribute: :custom_two, transform: MyOtherCustomTransform, priority: 2)
end

Transforms are applied in ascending order (lowest number first).

Note: Custom transformations are always applied after all built-in transformations, regardless of priority.

Custom asset file loader

An asset file loader returns a

String
representing a SVG document given a filename. Custom asset loaders should be a Ruby object that responds to a method called
named
, that takes one argument (a string representing the filename of the SVG document).

A simple example might look like this:

class MyAssetFileLoader
  def self.named(filename)
    # ... load SVG document however you like
    return "some document"
  end
end

Configure your custom asset file loader in an initializer like so:

InlineSvg.configure do |config|
  config.asset_file = MyAssetFileLoader
end

Caching all assets at boot time

When your deployment strategy prevents dynamic asset file loading from disk it can be helpful to cache all possible SVG assets in memory at application boot time. In this case, you can configure the

InlineSvg::CachedAssetFile
to scan any number of paths on disks and load all the assets it finds into memory.

For example, in this configuration we load every

*.svg
file found beneath the configured paths into memory:
InlineSvg.configure do |config|
  config.asset_file = InlineSvg::CachedAssetFile.new(
    paths: [
      "#{Rails.root}/public/path/to/assets",
      "#{Rails.root}/public/other/path/to/assets"
    ],
    filters: /\.svg/
  )
end

Note: Paths are read recursively, so think about keeping your SVG assets restricted to as few paths as possible, and using the filter option to further restrict assets to only those likely to be used by

inline_svg_tag
.

Missing SVG Files

If the specified SVG file cannot be found a helpful, empty SVG document is embedded into the page instead. The embedded document contains a single comment displaying the filename of the SVG image the helper tried to render:


You may apply a class to this empty SVG document by specifying the following configuration:

InlineSvg.configure do |config|
  config.svg_not_found_css_class = 'svg-not-found'
end

Which would instead render:


Alternatively,

inline_svg_tag
can be configured to raise an exception when a file is not found:
InlineSvg.configure do |config|
  config.raise_on_file_not_found = true
end

Contributing

  1. Fork it ( http://github.com/jamesmartin/inline_svg/fork )
  2. Create your feature branch (
    git checkout -b my-new-feature
    )
  3. Commit your changes (
    git commit -am 'Add some feature'
    )
  4. Push to the branch (
    git push origin my-new-feature
    )
  5. Create new Pull Request

Please write tests for anything you change, add or fix. There is a basic Rails app that demonstrates the gem's functionality in use.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.