Icons

Add any icon library to a Ruby app. Support for Lucide, Phosphor, Heroicons and others

Installation

Add the core gem to the Gemfile:

gem "icons"

Then run:

bundle install

Usage

The core gem is designed to be configured by higher-level layers (as seen with rails_icons) but can be used directly if needed.

Example:

Icons.configure do |config|
  config.icons_path = "app/assets/svg/icons"
  config.default_library = :lucide
  config.default_variant = :outline
end

# Sync any library from their respective (GitHub) repository
Icons::Sync.new("lucide").now

# Render an icon
icon = Icons::Icon.new(name: "check", library: "lucide", variant: "outline", arguments: { class: "text-gray-500" })
svg = icon.svg

# Generate SVG sprite for performance
sprite = Icons::Sprite.new(icons: ["check", "search"], library: "lucide", variant: "outline")
svg = sprite.svg
# => <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
#      <symbol id="lucide_outline_check" viewBox="0 0 24 24">...</symbol>
#      <symbol id="lucide_outline_search" viewBox="0 0 24 24">...</symbol>
#    </svg>

# Or configure globally
Icons.configure do |config|
  config.sprite = { lucide: { outline: ["check", "search"] } }
end

sprite = Icons::Sprite.new
sprite.svg

The resulting SVG will include the proper attributes and the SVG content from the library’s asset path.

Custom libraries

Add non first-party icon libraries. The Icons gem looks for SVGs at <icons_path>/<library_name>/<name>.svg, so any name works without configuration.

Zero config

Place SVGs at the expected path:

app/assets/svg/icons/my_icons/check.svg

Usage:

Icons::Icon.new(name: "check", library: "my_icons", arguments: {}).svg

Registered custom libraries

Use config.custom_library to declare a custom library with defaults:

Icons.configure do |config|
  config.custom_library :my_icons
end

Then set library specific defaults:

Icons.configure do |config|
  config.custom_library :my_icons

  config.libraries.my_icons.default.css = "size-6"
  config.libraries.my_icons.default.stroke_width = 1.5
end

Custom libraries with a git source

Pass a source: option to make a custom library syncable from a Git repository:

Icons.configure do |config|
  config.custom_library :my_icons, source: {
    url: "https://github.com/user/icons.git",
    variants: { default: "." }
  }
end

Icons::Sync.new(:my_icons).now

After syncing, Icons::Icon.new(name: "check", library: "my_icons", arguments: {}).svg , works just like any first party library.

First-party libraries

Libraries using Icons