{"id":13411786,"url":"https://github.com/jamesmartin/inline_svg","last_synced_at":"2025-05-14T13:09:26.650Z","repository":{"id":23579145,"uuid":"26947327","full_name":"jamesmartin/inline_svg","owner":"jamesmartin","description":"Embed SVG documents in your Rails views and style them with CSS","archived":false,"fork":false,"pushed_at":"2025-02-04T06:11:31.000Z","size":523,"stargazers_count":741,"open_issues_count":15,"forks_count":71,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-09T17:19:01.419Z","etag":null,"topics":["rails","ruby","sprockets","svg"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jamesmartin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-11-21T05:46:45.000Z","updated_at":"2025-04-08T15:41:02.000Z","dependencies_parsed_at":"2023-01-13T23:31:13.300Z","dependency_job_id":"5bb63fd8-f3a6-4b6f-b1a5-d8f19f8623e3","html_url":"https://github.com/jamesmartin/inline_svg","commit_stats":{"total_commits":386,"total_committers":41,"mean_commits":9.414634146341463,"dds":0.5259067357512953,"last_synced_commit":"10f0749249975ba50d6ee9b0f2c447852b38b980"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmartin%2Finline_svg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmartin%2Finline_svg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmartin%2Finline_svg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmartin%2Finline_svg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamesmartin","download_url":"https://codeload.github.com/jamesmartin/inline_svg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248074922,"owners_count":21043490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rails","ruby","sprockets","svg"],"created_at":"2024-07-30T20:01:16.917Z","updated_at":"2025-04-09T17:19:11.995Z","avatar_url":"https://github.com/jamesmartin.png","language":"Ruby","funding_links":[],"categories":["Ruby","Views and related"],"sub_categories":[],"readme":"# Inline SVG\n\n[![Ruby](https://github.com/jamesmartin/inline_svg/actions/workflows/ruby.yml/badge.svg)](https://github.com/jamesmartin/inline_svg/actions/workflows/ruby.yml)\n[![Integration Tests](https://github.com/jamesmartin/inline_svg/actions/workflows/integration_test.yml/badge.svg)](https://github.com/jamesmartin/inline_svg/actions/workflows/integration_test.yml)\n[![RuboCop](https://github.com/jamesmartin/inline_svg/actions/workflows/rubocop.yml/badge.svg)](https://github.com/jamesmartin/inline_svg/actions/workflows/rubocop.yml)\n\nStyling a SVG document with CSS for use on the web is most reliably achieved by\n[adding classes to the document and\nembedding](http://css-tricks.com/using-svg/) it inline in the HTML.\n\nThis gem adds Rails helper methods (`inline_svg_tag` and `inline_svg_pack_tag`) that read an SVG document (via Sprockets or Shakapacker, so works with the Rails Asset Pipeline), applies a CSS class attribute to the root of the document and\nthen embeds it into a view.\n\nInline SVG supports Rails 7.x with Propshaft, Sprockets, or Shakapacker\n\n## Changelog\n\nThis project adheres to [Semantic Versioning](http://semver.org). All notable changes are documented in the\n[CHANGELOG](https://github.com/jamesmartin/inline_svg/blob/master/CHANGELOG.md).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'inline_svg'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install inline_svg\n\n## Usage\n\n```ruby\n# Sprockets\ninline_svg_tag(file_name, options={})\n\n# Shakapacker\ninline_svg_pack_tag(file_name, options={})\n```\n\n_**Note:** The remainder of this README uses `inline_svg_tag` for examples, but the exact same principles work for `inline_svg_pack_tag`._\n\nThe `file_name` can be a full path to a file, the file's basename or an `IO`\nobject. The\nactual path of the file on disk is resolved using\n[Sprockets](://github.com/sstephenson/sprockets) (when available), a naive file finder (`/public/assets/...`) or in the case of `IO` objects the SVG data is read from the object.\nThis means you can pre-process and fingerprint your SVG files like other Rails assets, or choose to find SVG data yourself.\n\nHere's an example of embedding an SVG document and applying a 'class' attribute:\n\n```erb\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003ctitle\u003eEmbedded SVG Documents\u003ctitle\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003ch1\u003eEmbedded SVG Documents\u003c/h1\u003e\n    \u003cdiv\u003e\n      \u003c%= inline_svg_tag \"some-document.svg\", class: 'some-class' %\u003e\n    \u003c/div\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nHere's some CSS to target the SVG, resize it and turn it an attractive shade of\nblue:\n\n```css\n.some-class {\n  display: block;\n  margin: 0 auto;\n  fill: #3498db;\n  width: 5em;\n  height: 5em;\n}\n```\n\n## Options\n\nkey                     | description\n:---------------------- | :----------\n`id`                    | set a ID attribute on the SVG\n`class`                 | set a CSS class attribute on the SVG\n`style`                 | set a CSS style attribute on the SVG\n`data`                  | add data attributes to the SVG (supply as a hash)\n`size`                  | set width and height attributes on the SVG \u003cbr/\u003e Can also be set using `height` and/or `width` attributes, which take precedence over `size` \u003cbr/\u003e Supplied as \"{Width} * {Height}\" or \"{Number}\", so \"30px\\*45px\" becomes `width=\"30px\"` and `height=\"45px\"`, and \"50%\" becomes `width=\"50%\"` and `height=\"50%\"`\n`title`                 | add a \\\u003ctitle\\\u003e node inside the top level of the SVG document\n`desc`                  | add a \\\u003cdesc\\\u003e node inside the top level of the SVG document\n`nocomment`             | remove comment tags from the SVG document\n`preserve_aspect_ratio` | adds a `preserveAspectRatio` attribute to the SVG\n`view_box`              | adds a `viewBox` attribute to the SVG\n`aria`                  | adds common accessibility attributes to the SVG (see [PR #34](https://github.com/jamesmartin/inline_svg/pull/34#issue-152062674) for details)\n`aria_hidden`           | adds the `aria-hidden=true` attribute to the SVG\n`fallback`              | set fallback SVG document\n\nExample:\n\n```ruby\ninline_svg_tag(\n  \"some-document.svg\",\n  id: 'some-id',\n  class: 'some-class',\n  data: {some: \"value\"},\n  size: '30% * 20%',\n  title: 'Some Title',\n  desc: 'Some description',\n  nocomment: true,\n  preserve_aspect_ratio: 'xMaxYMax meet',\n  view_box: '0 0 100 100',\n  aria: true,\n  aria_hidden: true,\n  fallback: 'fallback-document.svg'\n)\n```\n\n## Accessibility\n\nUse the `aria: true` option to make `inline_svg_tag` add the following\naccessibility (a11y) attributes to your embedded SVG:\n\n* Adds a `role=\"img\"` attribute to the root SVG element\n* Adds a `aria-labelled-by=\"title-id desc-id\"` attribute to the root SVG\n  element, if the document contains `\u003ctitle\u003e` or `\u003cdesc\u003e` elements\n\nHere's an example:\n\n```erb\n\u003c%=\n  inline_svg_tag('iconmonstr-glasses-12-icon.svg',\n    aria: true, title: 'An SVG',\n    desc: 'This is my SVG. There are many like it. You get the picture')\n%\u003e\n```\n\n```xml\n\u003csvg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" \\\n  role=\"img\" aria-labelledby=\"bx6wix4t9pxpwxnohrhrmms3wexsw2o m439lk7mopdzmouktv2o689pl59wmd2\"\u003e\n  \u003ctitle id=\"bx6wix4t9pxpwxnohrhrmms3wexsw2o\"\u003eAn SVG\u003c/title\u003e\n  \u003cdesc id=\"m439lk7mopdzmouktv2o689pl59wmd2\"\u003eThis is my SVG. There are many like it. You get the picture\u003c/desc\u003e\n\u003c/svg\u003e\n```\n\n***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.\n\n## Custom Transformations\n\nThe transformation behavior of `inline_svg_tag` can be customized by creating custom transformation classes.\n\nFor example, inherit from `InlineSvg::CustomTransformation` and implement the `#transform` method:\n\n```ruby\n# Sets the `custom` attribute on the root SVG element to supplied value\n# Remember to return a document, as this will be passed along the transformation chain\n\nclass MyCustomTransform \u003c InlineSvg::CustomTransformation\n  def transform(doc)\n    with_svg(doc) do |svg|\n      svg[\"custom\"] = value\n    end\n  end\nend\n```\n\nAdd the custom configuration in an initializer (E.g. `./config/initializers/inline_svg.rb`):\n\n```ruby\n# Note that the named `attribute` will be used to pass a value to your custom transform\nInlineSvg.configure do |config|\n  config.add_custom_transformation(attribute: :my_custom_attribute, transform: MyCustomTransform)\nend\n```\n\nThe custom transformation can then be called like so:\n```haml\n%div\n  = inline_svg_tag \"some-document.svg\", my_custom_attribute: 'some value'\n```\n\nIn this example, the following transformation would be applied to a SVG document:\n\n```xml\n\u003csvg custom=\"some value\"\u003e...\u003c/svg\u003e\n```\n\nYou can also provide a default_value to the custom transformation, so even if you don't pass a value it will be triggered\n\n```ruby\n# Note that the named `attribute` will be used to pass a value to your custom transform\nInlineSvg.configure do |config|\n  config.add_custom_transformation(attribute: :my_custom_attribute, transform: MyCustomTransform, default_value: 'default value')\nend\n```\n\nThe custom transformation will be triggered even if you don't pass any attribute value\n```haml\n%div\n  = inline_svg_tag \"some-document.svg\"\n  = inline_svg_tag \"some-document.svg\", my_custom_attribute: 'some value'\n```\n\nIn this example, the following transformation would be applied to a SVG document:\n\n```xml\n\u003csvg custom=\"default value\"\u003e...\u003c/svg\u003e\n```\n\nAnd\n\n```xml\n\u003csvg custom=\"some value\"\u003e...\u003c/svg\u003e\n```\n\nPassing a `priority` option with your custom transformation allows you to\ncontrol the order that transformations are applied to the SVG document:\n\n```ruby\nInlineSvg.configure do |config|\n  config.add_custom_transformation(attribute: :custom_one, transform: MyCustomTransform, priority: 1)\n  config.add_custom_transformation(attribute: :custom_two, transform: MyOtherCustomTransform, priority: 2)\nend\n```\n\nTransforms are applied in ascending order (lowest number first).\n\n***Note***: Custom transformations are always applied *after* all built-in\ntransformations, regardless of priority.\n\n## Custom asset file loader\n\nAn asset file loader returns a `String` representing a SVG document given a\nfilename. Custom asset loaders should be a Ruby object that responds to a\nmethod called `named`, that takes one argument (a string representing the\nfilename of the SVG document).\n\nA simple example might look like this:\n\n```ruby\nclass MyAssetFileLoader\n  def self.named(filename)\n    # ... load SVG document however you like\n    return \"\u003csvg\u003esome document\u003c/svg\u003e\"\n  end\nend\n```\n\nConfigure your custom asset file loader in an initializer like so:\n\n```ruby\nInlineSvg.configure do |config|\n  config.asset_file = MyAssetFileLoader\nend\n```\n\n## Caching all assets at boot time\n\nWhen your deployment strategy prevents dynamic asset file loading from disk it\ncan be helpful to cache all possible SVG assets in memory at application boot\ntime. In this case, you can configure the `InlineSvg::CachedAssetFile` to scan\nany number of paths on disks and load all the assets it finds into memory.\n\nFor example, in this configuration we load every `*.svg` file found beneath the\nconfigured paths into memory:\n\n```ruby\nInlineSvg.configure do |config|\n  config.asset_file = InlineSvg::CachedAssetFile.new(\n    paths: [\n      \"#{Rails.root}/public/path/to/assets\",\n      \"#{Rails.root}/public/other/path/to/assets\"\n    ],\n    filters: /\\.svg/\n  )\nend\n```\n\n**Note:** Paths are read recursively, so think about keeping your SVG assets\nrestricted to as few paths as possible, and using the filter option to further\nrestrict assets to only those likely to be used by `inline_svg_tag`.\n\n## Missing SVG Files\n\nIf the specified SVG file cannot be found a helpful, empty SVG document is\nembedded into the page instead. The embedded document contains a single comment\ndisplaying the filename of the SVG image the helper tried to render:\n\n```html\n\u003csvg\u003e\u003c!-- SVG file not found: 'some-missing-file.svg' --\u003e\u003c/svg\u003e\n```\n\nYou may apply a class to this empty SVG document by specifying the following\nconfiguration:\n\n```rb\nInlineSvg.configure do |config|\n  config.svg_not_found_css_class = 'svg-not-found'\nend\n```\n\nWhich would instead render:\n\n```html\n\u003csvg class='svg-not-found'\u003e\u003c!-- SVG file not found: 'some-missing-file.svg' --\u003e\u003c/svg\u003e\n```\n\nAlternatively, `inline_svg_tag` can be configured to raise an exception when a file\nis not found:\n\n```ruby\nInlineSvg.configure do |config|\n  config.raise_on_file_not_found = true\nend\n```\n\n## Contributing\n\n1. Fork it ( [http://github.com/jamesmartin/inline_svg/fork](http://github.com/jamesmartin/inline_svg/fork) )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\nPlease write tests for anything you change, add or fix.\nThere is a [basic Rails\napp](http://github.com/jamesmartin/inline_svg_test_app) that demonstrates the\ngem's functionality in use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesmartin%2Finline_svg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesmartin%2Finline_svg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesmartin%2Finline_svg/lists"}