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.

# 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, ensuring Rails Icons remain lightweight.

Install

Add the gem

bundle add rails_icons

Install, choosing one of the supported libraries

rails generate rails_icons:install --libraries=LIBRARY_NAME

Example

rails generate rails_icons:install --libraries=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

Boxicons (1600+ icons)
Feather (280+ icons)
Flags (540+ icons)
Heroicons (300+ icons)
Linear (170+ icons)
Lucide (1500+ icons)
Phosphor (9000+ icons)
Radix (300+ icons)
SidekickIcons (49 icons, complementing Heroicons)
Tabler (5700+ icons)
Weather (215+ icons)

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 others libraries are available.

Custom icon library

Need to use an icon from another library?

run rails generate rails_icons:initializer --custom=simple_icons;
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 --libraries=heroicons

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