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

Want to make JavaScript your second-favorite language? 👉 JavaScript for Rails Developers

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?

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
• Helptail — Put your routine tasks on autopilot
• Forge — Self-hosted Community Software

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.