Icons gem for Phlex

Introduction

When it comes to building sleek, interactive UIs, having access to a robust set of icons is essential. Over the last few weeks, I've been migrating one of my projects from ERBs to Phlex. During this process, I found myself frequently reaching for SVG icons from popular libraries like Heroicons, Bootstrap icons, and Flag icons. After some frustration with manual integration into a Shared::Icon Phlex component, I had an idea - why not create a gem to simplify this process?

Thus, Phlex::Icons was born. This gem provides Phlex components for a variety of popular icon packs, all in one place. By leveraging the phlexing gem, Phlex::Icons automates the generation of over 12,000 icon components across seven different sources. Whether you're looking for a Bootstrap house icon, a Flag for a country, or a Heroicon for pagination, Phlex::Icons makes it easy.

Why I Built Phlex::Icons

Initially, I stumbled upon phlex-heroicons, which provided Phlex components for Heroicons. This was a great start, but I needed icons from other sources as well. After searching for a solution and coming up short, I decided to build a more generic solution. Phlex::Icons now supports:

• Bootstrap Icons (2,000+)
• Flag Icons (250+)
• Heroicons (300+)
• Lucide Icons (1,500+)
• RadixUI Icons (300+)
• Remix Icons (2,800+)
• Tabler Icons (4,800+)

With Phlex::Icons, you can seamlessly integrate these icons into your Phlex projects, dramatically cutting down the time spent on setting up and managing SVG icons.

Key Features of Phlex::Icons

• Centralized Icon Access: Phlex::Icons brings together multiple icon packs, offering developers more than 12,000 icons, eliminating the need for individual icon pack integration.
• Automatic Updates: A GitHub Actions workflow ensures icon packs are updated weekly. This means any new icons introduced by the source libraries are automatically included in your project.
• Flexible Integration: Don’t want to load all 12,000 icons into your app? You can use specific gems for individual icon packs like phlex-icons-bootstrap, phlex-icons-flag, phlex-icons-hero, phlex-icons-lucide, phlex-icons-radix, phlex-icons-remix, or phlex-icons-tabler.
• Lazy Loading: The gem supports lazy-loading icons, ensuring minimal impact on your app’s memory consumption.
• Phlex::Kit Integration: By leveraging Phlex::Kit, you can directly integrate icon packs into your UI components with minimal configuration, ensuring seamless rendering and a more streamlined workflow for Phlex projects.

Installation and Configuration

Getting started with Phlex::Icons is easy. To add it to your Rails project, simply execute:

bundle add phlex-icons

If you want more granular control and prefer adding individual icon packs, you can install specific packs like this:

bundle add phlex-icons-bootstrap
bundle add phlex-icons-hero

You can also configure global options for all icon packs, such as default CSS classes:

Phlex::Icons.configure do |config|
  config.default_classes = 'size-4'
end

Each icon pack can be further configured individually. For example, you can configure Flag icons to default to a rectangular variant:

Phlex::Icons::Flag.configure do |config|
  config.default_variant = :rectangle
end

Using Phlex::Icons in Your Application

Integrating Phlex::Icons into your project is straightforward. Here’s an example of how to use multiple icons in a view:

class PhlexIcons < Phlex::HTML
  include Phlex::Icons

  def view_template
    div do
      Bootstrap::House(classes: 'size-4')
      Flag::Sa(variant: :rectangle, classes: 'size-4')
      Hero::Home(variant: :solid, classes: 'size-4')
      Lucide::House(classes: 'size-4')
      Radix::Home(classes: 'size-4')
      Remix::HomeLine(classes: 'size-4')
      Tabler::Home(variant: :filled, classes: 'size-4')
    end
  end
end

Alternatively, if you don’t want to use Phlex::Kit, you can render the icons like this:

render Phlex::Icons::Bootstrap::House.new(classes: 'size-4')
render Phlex::Icons::Flag::Sa.new(variant: :rectangle, classes: 'size-4')
render Phlex::Icons::Hero::Home.new(variant: :solid, classes: 'size-4')
render Phlex::Icons::Lucide::House.new(classes: 'size-4')
render Phlex::Icons::Radix::Home.new(classes: 'size-4')
render Phlex::Icons::Remix::HomeLine.new(classes: 'size-4')
render Phlex::Icons::Tabler::Home.new(variant: :filled, classes: 'size-4')

Custom Icons

Phlex::Icons is designed with flexibility in mind, allowing you to add your custom icons as well. Simply create a phlex/icons/custom directory inside views/components and define your own icons within:

module Phlex
  module Icons
    module Custom
      class MyIcon < Phlex::Icons::Base
        def view_template
          # SVG code here
        end
      end
    end
  end
end

Now, you can use this custom icon like any other icon provided by Phlex::Icons:

render Phlex::Icons::Custom::MyIcon.new(classes: 'size-4')

Also, global configurations will be applied to the newly added icon.

Future Development and Contributions

Phlex::Icons is constantly evolving, and I’m always open to adding more icon packs and improving the gem’s functionality. If you have feedback or feature requests, feel free to open an issue or contribute to the project via GitHub. A big thanks to nejdetkadir for laying the groundwork with phlex-heroicons, which served as the foundation for this gem.

Conclusion

Phlex::Icons streamlines the process of integrating a wide range of icons into your Phlex projects. With over 12,000 icons and growing, this gem saves you the time and hassle of manually incorporating SVGs, while ensuring that your project stays up to date with the latest icon packs.

Give it a try, and let me know what you think! Contributions are always welcome on GitHub.

---

This post was inspired by my journey of migrating to Phlex and developing a better way to handle icons. If you’re working with Phlex, PhlexUI, or simply want to make your icon integration more efficient, Phlex::Icons might just be the solution you’ve been looking for.