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.

Sponsored By Rails Designer

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 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 --libraries=heroicons

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

Projects using Rails Icons

• Rails Designer UI Components — The first professionally-designed UI components library for Ruby on Rails apps
• Chirp Form — Add forms to any site. Display responses anywhere
• Helptail — Put your routine tasks on autopilot

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.