Rails Icons

Add any icon library to a Rails app. Rails Icons has first-party support for a handful of libraries. It is library agnostic so it can be used with any icon library using the same interface. Rails Icons is a Rails gem for the Icons Ruby gem.

Rails Icons - A collection of icons from popular libraries like Feather, Lucide, and Heroicons arranged in a grid pattern around the title text

# Using the default icon library
icon "check", class: "text-gray-500"

# Using any custom library
icon "apple", library: "simple_icons", class: "text-black"

The icons are sourced directly from their respective GitHub repositories via the Icons gem, ensuring Rails Icons remain lightweight.

Sponsored By Rails Designer

Rails Designer

Install

Add the gem:

bundle add rails_icons

Install, choosing one of the supported libraries:

rails generate rails_icons:install --library=LIBRARY_NAME

Example

rails generate rails_icons:install --library=heroicons

# Or multiple at once
rails generate rails_icons:install --libraries=heroicons lucide

The generator also mounts an icon preview at /rails_icons where you can browse and search all your available icons. This route is open by default, so restrict it in production if needed.

Usage

# Uses the default library and variant defined in config/initializer/rails_icons.rb
icon "check"

# Use another variant
icon "check", variant: "solid"

# Set library explicitly
icon "check", library: "heroicons"

# Add CSS
icon "check", class: "text-green-500"

# Add CSS with class_names
icon "check", class: ["size-4", "bg-red-500": !verified?, "bg-green-500": verified?]
# ↳ Article: https://railsdesigner.com/conditional-css-classes-in-rails/
# ↳ Documentation: https://edgeapi.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-token_list

# Add data attributes
icon "check", data: { controller: "swap" }

# Set the stroke-width
icon "check", stroke_width: 2

Sprites

Rails Icons supports SVG sprites for improved performance. Instead of inlining each icon's full SVG, sprite icons reference a shared set of <symbol> definitions via <use href="…">.

Configuration

# config/initializers/rails_icons.rb
RailsIcons.configure do |config|
  config.default_library = "heroicons"
  config.default_variant = "outline"

  # Where `sprite_icon` references symbols. Defaults to the gem-served
  # endpoint below. Set to nil to use inline mode (`<%= icons_sprite %>` in layout).
  config.default_sprite_location = "/rails_icons/sprite.svg"

  # Set to true to validate that referenced icons exist on disk
  config.validate_sprite_icons = false

  # Define which icons to include in the sprite
  config.sprite = {
    heroicons: {
      outline: %w[check chevron-down menu search x],
      mini: %w[check chevron-down]
    }
  }
end

External sprite (default)

Rails Icons serves the sprite at /rails_icons/sprite.svg out of the box — no controller, route or MIME type setup needed. The endpoint sits at the host app level, so it stays reachable even when the preview engine is mounted behind authentication.

<%= sprite_icon "check" %>
<%# renders: <svg><use href="/rails_icons/sprite.svg#heroicons_outline_check"></use></svg> %>

Point at a precompiled file or a CDN by changing the location:

config.default_sprite_location = "https://cdn.example.com/sprite_icons.svg"

Override per icon:

<%= sprite_icon "check", sprite_location: "/assets/sprites.svg" %>

Inline sprite

Set the location to nil and embed the sprite directly in your layout:

config.default_sprite_location = nil

<body>
  <%= icons_sprite %>

  <%= sprite_icon "check" %>
  <%= sprite_icon "search", class: "text-blue-500" %>
  <%= sprite_icon "menu", data: { controller: "nav" } %>
</body>

You can also generate a sprite for a specific set of icons:

<%= icons_sprite(["check", "search"], library: "heroicons", variant: "outline") %>

Helpers

sprite_icon accepts the same options as icon:

sprite_icon "check"
sprite_icon "check", library: "heroicons", variant: "mini"
sprite_icon "check", class: "size-6", data: { controller: "swap" }, stroke_width: 2
sprite_icon "check", sprite_location: "/sprite.svg"

icons_sprite generates the inline <svg> containing <symbol> definitions:

icons_sprite # all configured icons
icons_sprite ["check", "search"]  # specific icons
icons_sprite ["check", "search"], library: "heroicons", variant: "outline"  # with library/variant

First-party libraries

Animated icons

Rails Icons also includes a few animated icons. Great for loading states and so on. These are currently included:

  • faded-spinner
  • trailing-spinner
  • fading-dots
  • bouncing-dots

Use like this: icon "faded-spinner", library: "animated". The same attributes as the other libraries are available.

Custom icon library

Need to use an icon from another library (for example Simple Icons)?

  1. run rails generate rails_icons:initializer --custom=simple_icons;
  2. add the SVG icons to the created directory (app/assets/svg/icons/simple_icons);

Every custom icon can now be used with the same interface as first-party icon libraries:

icon "apple", library: "simple_icons", class: "text-black"

Sync icons

To sync all libraries, run:

rails generate rails_icons:sync

To sync only a specific library, run:

rails generate rails_icons:sync --library=heroicons

# Or multiple at once:
rails generate rails_icons:sync --libraries=heroicons lucide

Projects using Rails Icons

Contributing

This project uses Standard for formatting Ruby code. Please make sure to run be standardrb before submitting pull requests. Run tests via rails test.

License

Rails Icons is released under the MIT License.