Rails Icons

Add any icon library to a Rails app. Support for Lucide, Phosphor, Heroicons and others

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

# Or only specific variants
rails generate rails_icons:install --library=heroicons --variants solid outline

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.

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

To sync only specific variants for a library:

rails generate rails_icons:sync --library=heroicons --variants solid outline

Custom icon libraries

Rails Icons pulls SVGs straight from the path <icons_path>/<library_name>/<name>.svg. No generator is required for custom icons. Configuration is optional and only used to define defaults.

To add a custom library, create its directory and drop in your SVGs:

app/assets/svg/icons/simple_icons/apple.svg

(Alternatively, scaffold it with rails generate rails_icons:install --library=simple_icons, which creates the directory and adds config.custom_library :simple_icons in the initializer.)

Use them like any other library:

icon "apple", library: :simple_icons

To add a git source for syncing, edit the initializer:

RailsIcons.configure do |config|
  config.custom_library :my_icons, source: {
    url: "https://github.com/user/icons.git",
    variants: { default: "." }
  }
end

Then sync:

rails generate rails_icons:sync --library=my_icons

Projects using Rails Icons