Unmagic::Icon
Inline SVG icons for Rails, with downloadable icon libraries.
Features
- Render SVG icons inline as html-safe markup, straight into your views
- Resolve icons through
library/namereferences, with aliases and glob patterns - Per-library
manifest.jsonfor a default icon and alias mappings - Caller-controlled attributes (
class,aria-*,data-*, …) merged onto the<svg> - Rails engine that registers a
unmagic_iconview helper and sensible icon paths - One-command downloads for popular icon sets (Heroicons, Lucide, Tabler, Feather, and more)
- A Rack app for browsing your configured libraries
Installation
Add to your Gemfile:
gem 'unmagic-icon'Usage
In Rails views
The Rails engine registers a unmagic_icon helper and looks for icons in
vendor/icons and app/assets/icons (plus any engine-provided
app/assets/icons).
<%= unmagic_icon "heroicons/24-outline/star" %>
<%= unmagic_icon "lucide/check", class: "size-5 text-green-600" %>
<%= unmagic_icon "feather/menu", "aria-hidden": "true" %>An icon reference is library/name. The library is the directory the icon
lives in (relative to a configured path), and the name is the SVG file without
its extension. Nested libraries work too — heroicons/24-outline/star is the
star icon in the heroicons/24-outline library.
The rendered <svg> always gets a unmagic-icon class and a
data-unmagic-icon="library/name" marker. Any caller class is appended, and
every other option is merged verbatim as an attribute — so accessibility
(aria-hidden, aria-label, role), id, and data-* are entirely up to you.
Outside Rails
Configure the paths to look in, then resolve and render icons:
require "unmagic_icon"
Unmagic::Icon.init do |config|
config.paths = ["path/to/icons"]
end
icon = Unmagic::Icon.find("lucide/check")
icon.to_svg # => html-safe "<svg …>…</svg>"
icon.to_svg(class: "size-5") # => with an extra class
icon.as_json # => { name: "lucide/check", svg: "<svg …>" }References tolerate the emoji-style colon decoration, so ":lucide/check:"
resolves the same as "lucide/check".
Aliases and defaults
Drop a manifest.json into a library directory to declare a default icon and
aliases. Aliases can be exact names or glob patterns (patterns are matched
longest-first, so the most specific wins):
{
"default": "file",
"aliases": {
"*.rb": "ruby",
"*.test.tsx": "test",
"*.tsx": "react"
}
}Unmagic::Icon.find("material/app.rb").name # => "material/ruby"
Unmagic::Icon.find("material/unknown").name # => "material/file" (the default)Downloading icon libraries
The gem can fetch popular icon sets for you. List the ones you want in an initializer:
# config/initializers/unmagic_icon.rb
Unmagic::Icon.configure do |config|
config.libraries = [:heroicons, :lucide, :feather]
endThen download them (this also runs automatically during assets:precompile):
bin/rails unmagic:icons:installOr grab a single library on demand:
bin/rails unmagic:icons:download[heroicons]
bin/rails unmagic:icons:download[silk,force] # re-download even if presentLibraries are written to config.download_path (defaults to vendor/icons
under Rails), which keeps downloaded sets out of the asset pipeline — icons are
inlined via File.read, never served as assets.
Available libraries:
| Key | Title | Description |
|---|---|---|
heroicons |
Heroicons | Beautiful hand-crafted SVG icons by the makers of Tailwind CSS |
devicons |
Devicons | Icons representing programming languages, designing & development tools |
feather |
Feather Icons | Simply beautiful open source icons |
tabler |
Tabler Icons | Outline icons at tabler/name, filled icons at tabler/filled/name
|
lucide |
Lucide Icons | Beautiful & consistent icons |
simple-icons |
Simple Icons | SVG icons for popular brands |
material-file-icons |
Material File Icons | Material Design file icons with filename/extension aliases |
silk |
Silk Icons Scalable | The classic silk icon set recreated as SVG |
coloured-icons |
Coloured Icons | Full-colour brand and technology logos |
random-icons |
Random Icons | Keith Pitt's personal collection of SVG icons missing from other packs |
bootstrap-icons |
Bootstrap Icons | Official open source SVG icon library for Bootstrap |
octicons |
Octicons | Icons and icon font from GitHub |
iconoir |
Iconoir | Free open source icons designed on a 24x24 grid |
material-design-icons |
Material Design Icons | 7400+ Material Design icons (Pictogrammers @mdi) |
phosphor |
Phosphor Icons | Flexible icon family with six weights (thin to fill, plus duotone) |
lobe-icons |
Lobe Icons | Popular AI / LLM model brand logos and icons |
gilbarbara-logos |
Gil Barbara SVG Logos | Full-colour technology logos |
homarr-icons |
Homarr Dashboard Icons | Service logos with available light/dark variants |
carbon-pictograms |
IBM Carbon Pictograms | IBM pictograms including IBM Cloud |
aws-architecture-icons |
AWS Architecture Icons | Official 64px service SVGs; AWS usage terms apply |
Random Icons
keithpitt/random-icons is a growing
personal collection. Add SVGs directly to its icons/ directory and push to
main. The downloader follows main, so new icons do not require a gem release.
Unmagic::Icon.configure do |config|
config.libraries = [:"random-icons"]
endbin/rails 'unmagic:icons:download[random-icons]'
# Refresh after adding or changing icons upstream:
bin/rails 'unmagic:icons:download[random-icons,force]'An icons/example.svg file is available as random-icons/example. The pack
includes Rotten Tomatoes rating badges and colored/monochrome IMDb logos. A forced
refresh overwrites matching files but does not remove deleted icons. README,
per-asset attribution, sources.json, and any licenses/ directory are retained on download;
icons are subject to their individual terms, not the gem's MIT license.
Brand and cloud libraries
| Key | Pinned source | Example references |
|---|---|---|
gilbarbara-logos |
gilbarbara/logos, commit 37a6b807fd71c622efea27a9309b5d4edc792969
|
gilbarbara-logos/microsoft-power-bi, gilbarbara-logos/aws-cloudformation
|
homarr-icons |
homarr-labs/dashboard-icons, commit c716eb6798576923fa08e9b3e4125173148994ed
|
homarr-icons/powerbi, homarr-icons/dagster-light, homarr-icons/dagster-dark
|
carbon-pictograms |
@carbon/pictograms 12.85.0 |
carbon-pictograms/ibm--cloud |
aws-architecture-icons |
Official July 31, 2026 ZIP, SHA-256 verified | aws-architecture-icons/Arch_AWS-CloudFormation_64 |
Install these through the same initializer and task as other libraries:
Unmagic::Icon.configure do |config|
config.libraries = [:"gilbarbara-logos", :"homarr-icons", :"carbon-pictograms", :"aws-architecture-icons"]
endbin/rails unmagic:icons:install
# Or individually:
bin/rails 'unmagic:icons:download[gilbarbara-logos]'
bin/rails 'unmagic:icons:download[homarr-icons]'
bin/rails 'unmagic:icons:download[carbon-pictograms]'
bin/rails 'unmagic:icons:download[aws-architecture-icons]'<%= unmagic_icon "gilbarbara-logos/microsoft-power-bi", class: "size-6" %>
<%= unmagic_icon "gilbarbara-logos/aws-cloudformation" %>
<%= unmagic_icon "homarr-icons/powerbi" %>
<%= unmagic_icon "homarr-icons/dagster-light" %>
<%= unmagic_icon "homarr-icons/dagster-dark" %>
<%= unmagic_icon "carbon-pictograms/ibm--cloud" %>
<%= unmagic_icon "aws-architecture-icons/Arch_AWS-CloudFormation_64" %>
<%= unmagic_icon "aws-architecture-icons/Arch_AWS-Cloud-Development-Kit_64" %>
<%= unmagic_icon "aws-architecture-icons/Arch_Amazon-SageMaker_64" %>
<%= unmagic_icon "aws-architecture-icons/Arch_Amazon-SageMaker-AI_64" %>Names retain upstream spelling, case, punctuation, and variant suffixes. Select
light/dark assets explicitly; no automatic theme or product aliases are added.
SVG Logos' slim identifies the Slim PHP framework,
not the Ruby template language. Unknown products raise instead of falling
back to a parent-company logo.
Downloads copy logos/*.svg, svg/*.svg, and package/svg/*.svg, respectively,
into their library directories. Dashboard's archive also contains PNG/WebP and
website assets (a large download); only its top-level SVG assets are installed.
Carbon's @carbon/icons 11.89.0 and @carbon/pictograms 12.85.0 packages were
both inspected: the former has a UI-sized svg/32/ibm-cloud.svg; the latter has
the IBM Cloud pictogram svg/ibm--cloud.svg. This integration selects the
pictograms family, excludes src/svg duplicates and JavaScript, and preserves
the double hyphen in its canonical name. The UI icons package is not installed.
SVG Logos, Homarr Dashboard Icons, and Carbon retain the upstream license and README alongside the SVGs,
plus a manifest.json recording its source, exact revision/version and license.
SVG Logos also retains logos.json with the original product identities and
links. The downloader does not execute npm scripts or upstream code. Existing
libraries and saved references are unchanged; rendering uses the same inline
SVG pipeline. As with existing libraries, downloaded SVGs are trusted assets,
not sanitized untrusted uploads.
Attribution and redistribution
These assets are not covered by this gem's MIT license. Keep the downloaded legal files when redistributing them:
- SVG Logos: CC0-1.0. The upstream README identifies logos as their respective owners' property; CC0 does not waive trademark rights or third-party rights.
- Homarr Dashboard Icons: Apache-2.0, with copyright attribution to Bjorn Lammers, Meier Lukas, Thomas Camlong and Homarr Labs. Preserve the license and applicable notices; identify changes when distributing modified files. The README limits brand representations to identification and disclaims endorsement.
-
IBM Carbon Pictograms: Apache-2.0, as shipped in the pinned package's
LICENSEandREADME.md. Preserve these and applicable copyright notices; identify modifications. Apache-2.0 does not grant general trademark rights.
Neither pinned Apache archive contains a separate NOTICE file. SVG bytes are
copied unchanged; rendering adds the gem's normal wrapper attributes. If you
redistribute rendered or otherwise modified assets, retain the license and
applicable notices and identify your modifications.
AWS Architecture Icons
The aws-architecture-icons downloader fetches the official July 31, 2026 ZIP
directly from AWS. It verifies SHA-256
d2d166c453526471749d520e0db022c459abef759d2946cf2dd1d1c992dc6526
before extraction and installs only Architecture-Service-Icons_07312026/Arch_*/64/*.svg.
Upstream filenames and SVG bytes remain unchanged. Other sizes, resource icons,
category icons, raster files, and macOS metadata are excluded.
AWS assets are proprietary. The AWS Architecture Icons
page permits customers and partners to use them in architecture diagrams and
related materials. The AWS Site Terms and
AWS Intellectual Property License
apply; downloading through this gem does not grant general redistribution or
trademark rights. No separate license file is included in the archive. The
installer writes ATTRIBUTION.txt with AWS ownership, source and terms links,
usage constraints and the extraction/rendering changes, plus provenance in
manifest.json. No AWS assets are bundled in the gem. Check AWS's terms for
your intended use, especially before redistributing an icon pack.
The inspected official archive
contains the following distinct service SVGs under
Architecture-Service-Icons_07312026/:
| Product | Category / exact filename |
|---|---|
| CloudFormation | Arch_Management-Tools/64/Arch_AWS-CloudFormation_64.svg |
| AWS Cloud Development Kit | Arch_Developer-Tools/64/Arch_AWS-Cloud-Development-Kit_64.svg |
| Amazon SageMaker | Arch_Analytics/64/Arch_Amazon-SageMaker_64.svg |
| Amazon SageMaker AI | Arch_Artificial-Intelligence/64/Arch_Amazon-SageMaker-AI_64.svg |
| Amazon SageMaker Studio Lab | Arch_Artificial-Intelligence/64/Arch_Amazon-SageMaker-Studio-Lab_64.svg |
| Amazon SageMaker Ground Truth | Arch_Artificial-Intelligence/64/Arch_Amazon-SageMaker-Ground-Truth_64.svg |
Each filename above is installed at aws-architecture-icons/<filename-without-.svg>.
For example, Studio Lab is aws-architecture-icons/Arch_Amazon-SageMaker-Studio-Lab_64
and Ground Truth is aws-architecture-icons/Arch_Amazon-SageMaker-Ground-Truth_64.
SageMaker and SageMaker AI remain distinct, with no ambiguous sagemaker alias
or fallback to AWS's company logo. Source and licensing review: 2026-09-30.
Browsing icons
Unmagic::Icon::Web is a small Rack app for browsing your configured
libraries. Mount it in your routes:
mount Unmagic::Icon::Web => "/unmagic/icons"Development
After checking out the repo, install dependencies and run the tests:
bundle install
bundle exec rake specContributing
Bug reports and pull requests are welcome on GitHub at https://github.com/unreasonable-magic/unmagic-icon.
License
Released under the MIT License.