heroicons-ruby

Gem Version Heroicons Version

A simple Heroicons helper for Ruby on Rails.

bundle add heroicons-ruby

Usage

<!-- Render plain Heroicon SVG -->
<%= heroicon "arrow-right" %>

<!-- Use non-default variant -->
<%= heroicon "arrow-right", variant: :mini %>

<!-- Provide HTML attributes for the rendered SVG -->
<%= heroicon "arrow-right", class: "h-4 w-4", fill: "none" %>

Configuration

Valid variant values are %i[micro mini solid outline]. The default variant is solid however that default can be changed using:

# config/initializers/heroicons.rb
Heroicons.configure do |config|
  config.variant = :mini
end

If you would like to specify default HTML attributes (eg. class="h-4 w-4") for a given variant, you can configure that like so:

# config/initializers/heroicons.rb
Heroicons.configure do |config|
  config.attributes[:mini] = { class: "h-4 w-4" }
end

Rationale

Don't libraries already exist for this? Why make another?

The key differences between heroicons-ruby and others are:

  • Can be used without Rails (no need to pull in entire Rails dependency if not needed)
  • Renders exact Heroicons SVG identical to those found in the official repo. No transformations / differences from the official SVGs to worry about.
    • This also makes it very easy to keep this library up to date. On each new Heroicons release, all that needs to be done is a copy-paste of the official icons to the /icons folder.
  • Very thin API wrapper around <svg> making it easy and concise to configure HTML attributes. erb <%= heroicon "check", class: "h-4 w-4" %>
  • This library is used in production in numerous applications and given that I use TailwindCSS in all my projects, I'm highly incentivized to keep things up to date here. I can also guarantee that semantic versioning will be followed to ensure a stable API.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/narciero/heroicons-ruby.

License

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