Heroicon for Ruby on Rails

If you use default_class in your Heroicon configuration, you must ensure that the configuration file is included in your Tailwind CSS content paths. Otherwise, Tailwind may purge the classes used in the initializer, causing icons to appear without styling.

// tailwind.config.js
module.exports = {
  //...
  content: [
    './app/helpers/**/*.rb',
    './app/javascript/**/*.js',
    './app/views/**/*',
    './config/initializers/heroicon.rb', // Required if using default_class
  ],
  //...
}

To install Heroicon in your Ruby on Rails application, add the gem to your Gemfile and run the installer generator to create the necessary configuration files.

# Add to Gemfile
gem "heroicon"

$ bundle
$ rails g heroicon:install

Configuration is handled in config/initializers/heroicon.rb. You can set the global default variant and define default CSS classes that apply to all icons. The default_class can be a single String or a Hash mapping variants to specific classes.

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

To set up Heroicon in a Rails application, use the provided Rails generator. This will automatically create the necessary configuration initializer and the helper module required for using icons in your views.

Running the generator performs the following actions:

1. Creates config/initializers/heroicon.rb for gem configuration.
2. Creates app/helpers/heroicon_helper.rb to provide icon helper methods.

rails generate heroicon:install

Use the heroicon helper in your Rails views to render SVG icons. You can specify the icon name, a specific variant, and HTML options.

# Basic usage (defaults to :solid variant)
<%= heroicon "magnifying-glass" %>

# Specify a variant (:outline, :solid, or :mini)
<%= heroicon "magnifying-glass", variant: :outline %>

# Pass HTML options (like CSS classes)
<%= heroicon "magnifying-glass", options: { class: "text-primary-500" } %>

# Disable default classes configured in the initializer
<%= heroicon "magnifying-glass", options: { class: "custom-class", disable_default_class: true } %>

You can customize the global behavior of Heroicon by using the Heroicon.configure block. This allows you to set the default icon variant (e.g., :solid) and a default_class that will be applied to icons.

By default, the variant is set to :solid.

Heroicon.configure do |config|
  config.variant = :outline
  config.default_class = 'my-custom-icon-class'
end

You can set global default CSS classes for all icons or specify different classes for each variant (solid, outline, or mini) using the Heroicon.configure block. When rendering an icon, these classes are automatically prepended to the icon's class attribute. If you provide additional classes during rendering, they will be merged with the defaults and deduplicated.

To disable the automatic prepending of default classes for a specific icon instance, pass disable_default_class: true in the options.

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

# Rendering an icon will now include the variant-specific class
# Heroicon.render(name: 'user', variant: :solid)
# => <svg class="h-5 w-5">...</svg>