Anyicon

Gem Version

Anyicon provides Ruby on Rails view helpers for rendering icons from various collections hosted on GitHub.

How does it work

Anyicon simplifies the process of integrating and using SVG icons from various collections in your Rails application. Here's a breakdown of how it works:

  1. Configuration: You can set up the icon collections you want to use in a Rails initializer (config/initializers/anyicon.rb) or you can use the already defined collections. Each collection is defined by specifying the GitHub repository, the path within the repository where the icons are located, and the branch to use.

  2. Icon Rendering: When you call the anyicon helper in your views, it uses the Anyicon::Icon class to render the SVG content. The helper takes the icon name in the format collection:icon_name and optionally additional HTML properties.

  3. Fetching Icons: If the requested icon is not already cached locally, the gem will fetch the SVG file from the specified GitHub repository. It uses the configuration settings to construct the URL, download the file, and store it in your application's app/assets/images/icons directory. Attention to the license agreement of each collection

  4. Caching: Once downloaded, icons are cached locally to avoid repeated network requests. This ensures that your application remains performant and reduces dependency on external network availability.

  5. Helper Methods: The anyicon helper method simplifies the process of including icons in your views by managing the rendering and fetching process transparently. You can also pass additional HTML attributes to customize the rendered SVG element.

Installation

Add this line to your application's Gemfile:

gem 'anyicon'

And then execute:

bundle install

Or install it yourself as:

gem install anyicon

Usage

You can just use the anyicon helper in your views:

<%= anyicon icon: 'fontawesome_regular:address-book' %>

or

<%= anyicon 'fontawesome_regular:address-book' %>

Configuration

You can configure the icon collections in an initializer:

# config/initializers/anyicon.rb
Anyicon.configure do |config|
  config.collections = {
    my_custom_collection: { repo: 'user/repo', path: 'path/to/icons', branch: 'main' }
  }
end

Or add new collections while keeping the defaults:

Anyicon.configure do |config|
  config.add_collections(
    my_custom_collection: { repo: 'user/repo', path: 'path/to/icons', branch: 'main' }
  )
end

GitHub Token

Anyicon fetches icons from GitHub. Without authentication, the GitHub API limits requests to 60 per hour. If you use Anyicon::Collection to download entire collections, or your app fetches many icons on first deploy, you may hit this limit.

Setting a GitHub personal access token raises the limit to 5,000 requests per hour. The token is also used when downloading individual icons.

# config/initializers/anyicon.rb
Anyicon.configure do |config|
  config.github_token = ENV["GITHUB_TOKEN"]
end

To create a token, go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens and generate a token. No special permissions/scopes are needed — public repository read access is sufficient.

Note: This is optional. If you only use a few icons and they are already cached locally in app/assets/images/icons/, no API calls are made and no token is needed.

Collections Available

Collection Github List Example Quantity License
Font-Awesome fontawesome_regular fontawesome_regular:address-book 136 License
fontawesome_solid fontawesome_solid:award 1,392
fontawesome_brands fontawesome_brands:readme 490
Heroicons heroicons_outline heroicons_outline:check 296 MIT
heroicons_solid heroicons_solid:cube 296
Tabler Icons tabler_icons_filled tabler_icons_filled:alarm 675 MIT
tabler_icons_outline tabler_icons_outline:article 4,615
Mage Icons mage_icons_fill mage_icons_fill:Book 449 Apache 2.0
mage_icons_stroke mage_icons_stroke:Archive 545
mage_icons_social_bw mage_icons_social_bw:Github 50
mage_icons_social_color mage_icons_social_color:Youtube 50
Line Awesome line_awesome line_awesome:film 1,554 MIT/Good Boy License
@carbon/icons carbon carbon:arrow--left 2,212 Apache 2.0
IonIcons ionicons ionicons:add-sharp 1,356 MIT
Feather Icons feather_icons feather_icons:airplay 287 MIT

Please, read the license before using any of these collections. This gem does not maintain or keep any of those files in it's repository. However, when you use any of the icons they will be automatically saved in /app/assets/images/icons/ folder.

Fell free to add your own collection to this list.

Demo

To see Anyicon in action with an interactive demo page:

git clone https://github.com/arthurmolina/anyicon.git
cd anyicon
bundle install
RAILS_ENV=development bundle exec rackup -p 3000 test/dummy/config.ru

Then open http://localhost:3000/demo.

The demo showcases basic usage, sizing, colors, HTML/data/aria attributes, inline text components, and CSS animations.

Development

To get started with development:

git clone https://github.com/arthurmolina/anyicon.git
cd anyicon
bundle install
bundle exec rake test

Contributing

Anyone is encouraged to help improve this project. Here are a few ways you can help:

License

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