Heroicons

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

This gem has no official affiliation with Tailwind CSS or the Heroicons team. Check out their sites:

Installation

Add this line to your application's Gemfile:

gem "heroicons"

And then execute:

$ bundle

Run the installer

$ rails g heroicons:install

Usage

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

<%= heroicon "magnifying-glass" %>

Heroicons comes with 4 variants, :outline, :solid, :mini, and :micro. The default variant is :solid. This can be changed in config/initializers/heroicons.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" } %>

Heroicons currently supports icons matching Version 2.1.3. 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 heroicons:install in the installation step, a configuration file will be created at config/initializers/heroicons.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, :solid, :mini, or :micro. 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/initializers/heroicons.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/heroicons.rb', // 👈
  ],
  //...
}

An example configuration looks like this:

Heroicons.configure do |config|
  config.variant = :solid
  config.default_class = {
    solid: "size-6",
    outline: "size-6",
    mini: "size-5",
    micro: "size-4",
  }
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/jclusso/heroicons.git
cd heroicons
bundle install
bundle exec rake test

License

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