Kiso Icons 基礎

Iconify icons for Rails. Use any of 224 icon sets (299k+ icons) as inline SVG. No JavaScript needed.

Icons live in vendor/icons/ as JSON files. Commit them to git.

Part of the Kiso 基礎 family. Works on its own in any Rails 8+ app.

./bin/bundle add kiso-icons
./bin/rails kiso_icons:install

This creates vendor/icons/ and a bin/kiso-icons binstub.

Lucide ships with the gem. Use it right away:

<%= kiso_icon_tag("check") %>
<%= kiso_icon_tag("arrow-right") %>

Want a different icon set? Pin it:

./bin/kiso-icons pin heroicons

Then use it with the set name as a prefix:

<%= kiso_icon_tag("heroicons:home") %>

Browse all sets at icon-sets.iconify.design.

<%= kiso_icon_tag("lucide:check") %>
<%= kiso_icon_tag("check") %>                          <%# uses the default set (lucide) %>
<%= kiso_icon_tag("check", class: "w-5 h-5") %>       <%# add CSS classes %>
<%= kiso_icon_tag("check", aria: { label: "Done" }) %> <%# screen reader label %>

You can pass any HTML attribute. If you add aria: { label: "..." }, screen readers will see the icon and aria-hidden is removed.

The pin command downloads an Iconify JSON file to vendor/icons/. Commit it to git.

./bin/kiso-icons pin lucide             # pin Lucide (replaces the bundled copy)
./bin/kiso-icons pin heroicons mdi      # pin more than one set at once
./bin/kiso-icons unpin heroicons        # remove a set
./bin/kiso-icons pristine               # re-download all pinned sets
./bin/kiso-icons list                   # show what's pinned

Add an initializer to change the defaults:

# config/initializers/kiso_icons.rb
Kiso::Icons.configure do |config|
  config.default_set = "lucide"        # icon set used when no prefix is given
  config.vendor_path = "vendor/icons"  # where pinned JSON files are stored
end

Icons are found in this order:

1. Pinned JSON — your sets in vendor/icons/
2. Bundled Lucide — ships with the gem (81 KB gzipped), works with no setup

Each SVG uses width="1em", height="1em", and currentColor. It inherits its size from font-size and its color from the parent element. No CSS framework needed.

git clone https://github.com/steveclarke/kiso-icons.git
cd kiso-icons
bin/setup    # install deps + pin demo icon sets
bin/dev      # start demo app at http://localhost:3100

bin/dev starts a Rails app that shows icons from 10 sets. You can change the port: bin/dev 4200.

Run tests:

bin/rake test              # unit tests (no Rails)
bin/rake test_integration  # integration tests (boots Rails)
bin/rake                   # both
bin/standardrb             # lint (StandardRB)
bin/standardrb --fix       # auto-fix lint

See CONTRIBUTING.md to help out.

bin/           dev scripts and CLI binstub
data/          bundled Lucide icon set (gzipped JSON)
lib/           gem source code
test/          unit and integration tests
test/dummy/    Rails app used for integration tests and the demo

• Ruby >= 3.2
• Rails >= 8.0

MIT License. See MIT-LICENSE.