abeidahmed / rails-heroicon

Ruby on Rails views helpers for the awesome heroicons by Steve Schoger.

Rails Heroicon

Ruby on Rails views helper for the awesome heroicons by Steve Schoger. To see all the icons visit heroicons.

The latest version of this gem is built with heroicons v2.1.3 (288 icons).

This gem has no official affiliation with Tailwind Labs, yet.

Installation

Add this line to your application's Gemfile:

gem "rails_heroicon"

And then execute:

bundle install

Or install it yourself as:

gem install rails_heroicon

Usage

After installing the gem, call <%= heroicon "user" %> on your erb template. The first argument is the icon name. All the icons are listed here.

This will generate the following html:

<svg
  xmlns="http://www.w3.org/2000/svg"
  aria-hidden="true"
  width="24"
  height="24"
  viewBox="0 0 24 24"
  fill="none"
  stroke="currentColor"
  stroke-width="1.5"
  version="1.1"
>
  <path
    d="M16 7C16 9.20914 14.2091 11 12 11C9.79086 11 8 9.20914 8 7C8 4.79086 9.79086 3 12 3C14.2091 3 16 4.79086 16 7Z"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  />
  <path
    d="M12 14C8.13401 14 5 17.134 5 21H19C19 17.134 15.866 14 12 14Z"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
  />
</svg>

Note: Indentation is for readability purpose.

Variant

rails_heroicon provides 4 variants, outline, solid, mini, and micro, outline being the default.

To change the variant <%= heroicon "user", variant: "solid" %>.

HTML attributes

Any html and eruby attribute is supported, for eg:

<%= heroicon "user", class: "text-gray-500", aria: { label: "user-icon" } %>

Handling the size of the icon

Normally, if you're just using vanilla heroicons with Tailwind CSS, you'd add w-5 h-5 as classes on the svg element. With rails_heroicon, you just need to set the size attribute on the helper method.

<%= heroicon "user", size: 20 %>

If the variant is set as outline or solid, size defaults to 24, if the variant is set as mini, size defaults to 20, and if the variant is set as micro, size defaults to 16. However, this can be over-written with the size attribute.

Accessibility

rails_heroicon automatically sets aria-hidden="true" if aria-label is not set, and if aria-label is set, then role="img" is set.

Tooltip

You can provide tooltips on hover if you pass in a title option. Anything passed into the title option will be rendered inside of a <title> tag within the rendered SVG, which modern browsers will lean on to display a tooltip on hover.

Development

• Clone the repo
• Run bundle install, or run ./bin/setup
• Run bundle exec rake to run the tests to see if it passing

Publishing

• gem build rails_heroicon.gemspec
• gem push rails_heroicon-x.x.x.gem

Contributing

Bug reports and pull requests are welcome. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Please read the CONTRIBUTING.md on how to make pull requests.

License

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

Code of Conduct

Everyone interacting in the Rails Heroicon project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Similar projects

• rails_feather - Ruby on Rails views helper method for rendering beautiful feather icons.

rails-heroicon's Issues

[feature] Allow customization of the cache through ActiveSupport caching

This is a feature request. icon_cache is using a Hash by default

It would be great to:

1. Set the cache as a config.cache_store in the Railtie
2. Use a Rails null store or memory store by default

This will allow sharing the cache with multiple server processes. E.g. with Memcached

Automate keeping this gem up to date by checking the official heroicons repo for new releases in a GitHub Action

This is in reference to issue #33 where we may want to define a workflow to help keep this gem up to date based on new versions of heroicons being available from the official tailwindlabs/heroicons repo:

A daily or weekly script could:

1. Check https://github.com/tailwindlabs/heroicons/releases/latest which redirects to the latest release
   • You can use GitHub's API to grab the specific version
2. Modify your gem to store the version you're using so it can be compared to the latest version
   • Option 1: Use v2.0.16.json instead of icons.json, but this will make git diffing hard since the file name changed?
   • Option 2: Add a _version field to the icons.json, not bad but feels like it's mixing concerns of icons and metadata?
   • Option 3: Write a separate TAILWINDLABS_HEROICONS_VERSION file somewhere within the gem, pretty good?
3. A script compares the latest version to any of the above options, if there's a difference:
   • Make a new branch in your repo
   • Clone https://github.com/tailwindlabs/heroicons
   • Copy all of the tailwindlabs/heroicons icons into your repo's icons folder
     • Is there a difference between src/ and optimized/?
   • Update your version based on step 2
   • Update your readme to reference the version from what I added in this issue's PR
   • Commit the changes and push the branch
   • Open a PR in your own repo so you can review it as a human

At this point you can merge it and cut a gem release. I don't know your workflow for updating the changelog but that step could be done manually in the PR or after you merge it but before you build a new gem.

Step 2's option 3 looks like the most appealing based on feedback from @abeidahmed.

As for testing the script:

For development I'd suggest creating it all as an offline script that you can run on the command line on your dev box without needing to push any commits. This way it can be tested in isolation with a number of different inputs. Then once it's good to go drop it into a GitHub Action.

As a first-time-end-to-end test maybe a 2nd private repo could be created just to make sure the GitHub Action portion works. I don't really know of a better way to test GitHub Actions unless you start looking into solutions like https://github.com/nektos/act (I haven't yet btw).

Document the version of Herocions this gem supports?

Hi,

Great gem!

I'm about to try it out and was wondering if you were open to documenting the version of Herocions used in the readme file?

I know it mentions there's 292 icons which matches the 292 icons available in Heroicons v2.0.16 based on viewing https://heroicons.com/ at the time of making this issue (it may change in the future).

For folks who might be on the fence on trying this out, it would be beneficial to see something like:

The latest rails_heroicon is built with Heroicons v2.0.16 (292 icons)

On that note, are you programmatically syncing releases to Tailwindlabs' repo or is it done manually?

Ability to customise the defaults

Thank you for this gem!

Typically one will follow mostly the same options (variant, size, etc.), across their UI. If the desired style is not what is set as the default (outline, 24px), it is required to set the options for every icon and if later you want to change any of the options, you have to go and update every instance.

What do you think about exposing the defaults for customisation, so e.g. one can set the defaults they want and only overwrite when needed?

Add rails as dependency

• rails dependency is missing on the gemspec

Custom stroke is being applied in the HTML for the svg and path, but the path doesn't get updated

Here's the same icon being rendered with this gem and straight from heroicons if you copy / paste the SVG.

<%= heroicon "question-mark-circle", size: 16, "stroke-width" => 2 %>

It produces this HTML:

<svg stroke-width="2" viewBox="0 0 24 24" height="16" width="16" version="1.1" fill="none" stroke="currentColor" aria-hidden="true">
  <path d="M9.87891 7.51884C11.0505 6.49372 12.95 6.49372 14.1215 7.51884C15.2931 8.54397 15.2931 10.206 14.1215 11.2312C13.9176 11.4096 13.6917 11.5569 13.4513 11.6733C12.7056 12.0341 12.0002 12.6716 12.0002 13.5V14.25M21 12C21 16.9706 16.9706 21 12 21C7.02944 21 3 16.9706 3 12C3 7.02944 7.02944 3 12 3C16.9706 3 21 7.02944 21 12ZM12 17.25H12.0075V17.2575H12V17.25Z" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
  </path>
</svg>

Here's the HTML straight from heroicons' website if you paste the svg:

<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="w-4 h-4">
  <path stroke-linecap="round" stroke-linejoin="round" d="M9.879 7.519c1.171-1.025 3.071-1.025 4.242 0 1.172 1.025 1.172 2.687 0 3.712-.203.179-.43.326-.67.442-.745.361-1.45.999-1.45 1.827v.75M21 12a9 9 0 11-18 0 9 9 0 0118 0zm-9 5.25h.008v.008H12v-.008z" />
</svg>

And here's a screenshot (left = this gem, right = heroicons website):

This isn't limited to the question-mark-circle icon. This happens with all of the icons I've tried. This gem puts (2) different strokes. One on the svg and one on the path, but the path's stroke is never set. I don't think we need to set it on the path since it's not set on the official heroicons site?

Also the path is much longer with your gem vs what's pasted from the hericons site.

Add ability to add title tags to enable SVG tooltips

It would be awesome to be able to do something like

<%= heroicon "bookmark", alt: "Bookmark this widget" %>

Anything provided to :alt option would end up in a <title> tag nested in the SVG element, which browsers turn into tooltips on hover.

Are there any opportunities to increase the performance? Loading 500 icons takes ~45ms but loading the svgs directly takes ~5ms

I noticed when I don't use this gem my pages respond in 4-5ms in the dev console.

When I output 20 heroicons with this gem it doubles to about 10ms and with 500 heroicons it jumps to 45ms.

If I view the source code of what your gem provided with those 500 heroicons and copy all of the svgs and use them directly in my erb template without calling your gem, the same page renders in ~5-10ms (variance).

Are there any spots to optimize how this gem loads and picks the icon?

I noticed lib/rails_heroicons.rb has:

module RailsHeroicon
  ICON_PATH = File.join(File.dirname(__FILE__), "../compressed/icons.json")
  ICONS = JSON.parse(File.read(ICON_PATH)).freeze
end

I patched that to this:

module RailsHeroicon
  ICON_PATH ||= File.join(File.dirname(__FILE__), "../compressed/icons.json").freeze
  ICONS ||= JSON.parse(File.read(ICON_PATH)).freeze
end

But it didn't make a difference. I verified the patch was active because I tried to redefine ICON_PATH and Ruby said I can't since it was previously defined which makes me think the patch was successful. I dropped that into a Rails initializer.

Any suggestions on what we can do to further optimize things?

In my opinion it's worth it because it's very possible to render 50-100 icons on 1 page. Imagine a table where you return 25 rows but each row has 3 icons. That's 75. If you return 50 rows suddenly that's 150 heroicons.