Heroicon

Ruby on Rails view helpers for the beautiful hand-crafted SVG icons, Heroicons.

Used in production at beehiiv 🐝

This gem has no official affiliation with Tailwind CSS or the Heroicon team (yet!). Check out their sites:

Installation

Add this line to your application's Gemfile:

gem "heroicon"

And then execute:

$ bundle

Run the installer

$ rails g heroicon:install

Usage

To use a icon in your views, simply use the provided view helper with the name of an icon.

<%= heroicon "magnifying-glass" %>

Heroicon comes with 3 variants, :outline, :solid and :mini. The default variant is :solid. This can be changed in config/initializers/heroicon.rb, which is generated during installation (See Configuration). To overwrite this in the view, use

<%= heroicon "magnifying-glass", variant: :outline %>

You can also pass HTML options directly to the icon.

<%= heroicon "magnifying-glass", options: { class: "text-primary-500" } %>

Heroicon currently supports icons matching Version 2.0.10. If there is an icon that is missing or a new version released, feel free to contribute by following our contributing guide below.

Configuration

After running rails g heroicon:install in the installation step, a configuration file will be created at config/initializers/heroicon.rb.

Currently there are two configuration options:

variant: The default variant to use if no variant is specified in the view.
- You can set this to either :outline or :solid. Defaults to :solid.
default_class: A default class that gets applied to every icon.
- This accepts either a String to apply to every icon, or a Hash, which applies the class based on the variant of the icon (see the example below).
- You can disable this on a per-icon basis by passing disable_default_class: true in the options hash within the view.

Note: If you enable the default_class config, make sure to include config/intializers/heroicon.rb in the list of purged paths. For TailwindCSS 3.0+, you should have something like this in your tailwind.config.js:

module.exports = {
  //...
  content: [
    './app/helpers/**/*.rb',
    './app/javascript/**/*.js',
    './app/views/**/*',
    './config/initializers/heroicon.rb', // 👈
  ],
  //...
}

An example configuration looks like this:

Heroicon.configure do |config|
  config.variant = :solid
  config.default_class = {solid: "h-6 w-6", outline: "h-6 w-6", mini: "h-5 w-5"}
end

Disabling the default class in the view:

<%= heroicon "magnifying-glass", options: { class: "custom-class", disable_default_class: true } %>

Contributing

Anyone is encouraged to help improve this project. Here are a few ways you can help:

Report bugs
Fix bugs and submit pull requests
Write, clarify, or fix documentation
Suggest or add new features

To get started with development:

git clone https://github.com/bharget/heroicon.git
cd heroicon
bundle install
bundle exec rake test

License

The gem is available as open source under the terms of the MIT License.

heroicon