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

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

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