railsui_icon

Rails UI - Icon

This is a standalone gem from the maker of Rails UI aimed at making rendering heroicons (with more icons to come in the future) in Rails applications easier.

Installation

Add this line to your application's Gemfile:

gem "railsui_icon"

And then execute:

bundle install

Run the installer

rails g railsui_icon:install

The installer creates a new initializer where you can assign some defaults. A variant is required. Choose from :solid, :outline, :mini, and :micro.

# config/initializers/railsui_icon.rb

RailsuiIcon.configure do |config|
  # Set the default icon variant (:solid, :outline, :mini, :micro)
  config.default_variant = :outline

  # Optionally set default classes that apply to every icon with the given variant.
  # Make sure to update your Tailwind CSS config if you enable this setting.
  # content: [
  #  "./config/initializers/railsui_icon.rb",
  # ],

  config.default_class = {
    solid: "fill-current",
    outline: "size-5",
    mini: "size-3 fill-current",
    micro: "size-3 fill-current"
  }
end

Optionally set a default_variant and default_class which dictate how icons will render.

The gem will attempt to update a tailwind configuration automatically if you have one at the root of your project.

If you have a tailwind configuration elsewhere in your project be sure to update your content paths to include the new initializer.

// tailwind.config.js

module.exports = {
  content: [
    "./config/initializers/railsui_icon.rb",
    // ...
  ],
}

Usage

Render icons with the icon helper method:

<%= icon "star" %>

Base rendering using the default variant of :outline.

Options

Variants

Options: - outline - default, solid, mini, micro

Pass the variant: option to the icon helper with the appropriate variant in symbol form to modify with icon loads.

<%= icon "star", variant: :micro %>
<%= icon "star", variant: :mini %>
<%= icon "star", variant: :outline %>
<%= icon "star", variant: :solid %>

Add CSS classes

<%= icon "star", class: "size-8 text-red-500 stroke-current" %>

Disable default classes

If you set default classes in your configuration you can disable those explicitly in one-off scenarios that might require it.

<%= icon "star", disable_default_class: true %>

Pass a custom icon path

Additional icons can be sourced from app/assets/images. Pass a custom path to render those. It's assumed the icon will be the .svg format. The path should be relative with a leading slash.

• An icon name or nil value for the name is still required.
• The file suffix is required in this scenario.

<!-- Resolves from app/assets/images/logo.svg -->

<%= icon "logo", custom_path: "/logo.svg" %>

The kitchen sink

<%= icon "star", variant: :micro, class: "size-3 fill-current text-pink-500", custom_path: "/my_icons/star.svg", disable_default_class: true %>

Bugs

Spot something off? Open an issue on the GitHub repo. PRs welcomed!

License

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

Rails UI

Build Ruby on Rails apps faster than ever with Rails UI.

Rails UI features professionally designed components and templates for Ruby on Rails. Leverage breath-taking UI to fast-track your next idea.