Rails Icons

To use Rails Icons in your Rails application, add the gem to your Gemfile and run the installation generator. You can specify one or more supported libraries and specific variants during installation.

Note: The generator also mounts an icon preview at /rails_icons for browsing and searching. This route is open by default; ensure you restrict it in production environments.

# Add the gem
bundle add rails_icons

# Install a single library
rails generate rails_icons:install --library=heroicons

# Install multiple libraries at once
rails generate rails_icons:install --libraries=heroicons lucide

# Install specific variants
rails generate rails_icons:install --library=heroicons --variants solid outline

Use the Rails generator to create the config/initializers/rails_icons.rb configuration file. This file is used to define your default icon library, variants, custom icon paths, and library registrations.

Available CLI options:

• --library: Choose a single library to include.
• --libraries: Choose multiple libraries (array).
• --destination: Specify a custom icons folder path (defaults to the current RailsIcons.configuration.icons_path).

rails generate rails_icons:initializer --library heroicons --libraries lucide --destination app/assets/icons

Run the rails_icons:install generator to set up the configuration initializer and sync your chosen icon libraries. This command allows you to specify which libraries to include, where to store them, and which variants to sync.

rails generate rails_icons:install --library=heroicons --variants=solid outline

The rails_icons project includes a Ruby LSP addon that provides autocompletion for the icon method. When using Ruby LSP, typing icon " will trigger a list of available icon names based on the SVG files found in your project's icon directories.

By default, the addon indexes icons from:

1. The path configured via RailsIcons.configuration.icons_path (defaults to app/assets/svg/icons).
2. A sub-directory defined by RailsIcons.configuration.default_library within that path.

To ensure autocompletion works correctly, make sure your icons are stored in the expected directory or explicitly configure the path in your Rails initializer.

# Example of how the autocompletion is triggered in your code
icon "home"

Rails Icons includes a special animated library containing icons suitable for loading states.

Available animated icons:

• faded-spinner
• trailing-spinner
• fading-dots
• bouncing-dots

Usage:

icon "faded-spinner", library: "animated"

The config/initializers/rails_icons.rb file allows you to manage how icons are loaded and accessed. Key configuration options include:

• config.default_library: Sets the fallback library if none is specified.
• config.default_variant: Sets a default variant (e.g., 'outline' or 'solid') for all libraries.
• config.icons_path: Defines the directory where icon files are stored.
• config.custom_library :name: Registers a custom library folder.

Example configuration structure:

RailsIcons.configure do |config|
  config.default_library = "heroicons"
  # config.default_variant = ""
  # Default icons path
  config.icons_path = "app/assets/icons"

  # First-party library configurations are injected here

  config.custom_library :my_custom_icons
end

You can configure the RailsIcons gem within a Rails initializer (e.g., config/initializers/rails_icons.rb). The configuration block allows you to set the base path for icon assets and manage sprite settings.

Available configuration keys:

• base_path: The root directory used to resolve icon paths (defaults to Rails.root).
• sprite: A hash for sprite-specific configuration.
• default_sprite_location: The URL path where the generated sprite SVG will be served (defaults to "/rails_icons/sprite.svg").
• validate_sprite_icons: A boolean determining whether to validate icons during sprite generation (defaults to false).

RailsIcons::Icons.configure do |config|
  config.base_path = Rails.root
  config.default_sprite_location = "/custom/path/sprite.svg"
  config.validate_sprite_icons = true
  config.sprite = {
    # sprite specific settings
  }
end