Skip to content


Repository files navigation


Minimalistic ruby gem that exposes a tag helper for Font Awesome icon sets.

By design it does not bundle any icons making it super fast to download and install as well as providing the ability to use new icons as they become available, custom ones or the PRO collection.

Gem Version
Gitter chat


Add this line to your application's Gemfile:

gem 'faw_icon'

And then execute:

$ bundle

Or install it yourself as:

$ gem install faw_icon

You will need to download the .zip folder from Font Awesome where you can choose either the free or the PRO collection.

Include in your application.scss the fontawesome/css/svg-with-js.css ideally placing in the app/assets/stylesheets/fontawesome/svg-with-js.css


@import "svg-with-js.min";
@import "fontawesome/all";


The below options are also available for further customization

Property Default
icons_path app/assets/javascripts/icons.json
raw_svg_path vendor/fa5/raw-svg
svg_sprites_path public/fa5/svg-sprites
source_type json (json, raw, sprite, js)
icon_not_found <svg>...</svg>
default_family_prefix fa
default_replacement_class svg-inline--fa

Simply create an initializer under /config/initializers/faw_icon.rb and modify as needed ! If you no option is supplied the default will be used

FawIcon.configure do |config|
  config.icons_path = 'app/assets/javascripts/icons.json'
  config.default_family_prefix = 'fa'
  config.default_replacement_class = 'svg-inline--fa'

The configuration option source_type was added to address the performance hit from loading large json files from the PRO collection and introduces several ways to include icons in the application.

  1. json load a json file, traverse and find the icon
  2. raw load a single svg file from the filesystem
  3. sprite load an svg sprite and target the icon by using svg fragment identifiers
  4. js load one or more .js files according to the recommended way described at svg-with-js

They all have pros and cons so choose the one that is right for you.

json a single file that contains everything however it will have a noticeable impact on performance when used with the PRO collection because of the file size but not so much with the free one or a reduced set. In order to use copy the fontawesome/metadata/icons.json in app/assets/javascripts/icons.json

raw requires to push in your codebase all 2.986 icons unless they are hosted in a CDN, AWS or just a different repo. And keep them under vendor/fa5

with sprite you only need four files but they can only be served from public folder for the fragment identifier feature to work which makes them available for anyone to download whereas the raw ones are 'hidden' in the vendor folder.

Read more about svg sprites in the docs

js uses the recommended way from Font-Awesome however it introduces a rendering issue relating to turbolinks more info

However the paths to the icons can be configured and as long the parent folder with the style name i.e. solid, regular and so on remains the same feel free to place anywhere you like and if possible share your solution !

It is best not to mix the source_type configurations if you decide to switch between two types make sure to keep only the assets relating to that source_type in order to avoid manifestations of unexpected behavior.

At the same time feel free to create a pull request if you have another idea on how to include them or create an issue requesting a missing feature.


All options from additional-styling are supported with the exception of CSS Pseudo-elements.

A mapping for the properties has been introduced in an attempt to make them more readable and easier to remember

Original property Mapped property Required Original value Mapped value Type
class style yes fas, far, fal, fab, fad solid, regular, light, brand, duotone string
class name yes fa-user user string
class fixed_width no fa-fw true boolean
class spin no fa-spin true boolean
class extra_class no N/A any custom css class string
data-fa-transform transform no grow-6 grow-6 string
data-fa-mask mask no fas fa-comment fas fa-comment string

The style and name are required params and the rest optional ones go into a Hash in any order they might occur.

Then just use them like this

  <%= faw_icon 'solid', 'magic' %>
  <%= faw_icon 'solid', 'star', {extra_class: 'active'} %>
  <%= faw_icon 'solid', 'user', {size: '10x'} %>
  <%= faw_icon 'light', 'info', {fixed_width: true} %>
  <%= faw_icon 'regular', 'sync', {spin: true} %>
  <%= faw_icon 'brand', 'android', {transform: 'grow-5'} %>
  <%= faw_icon 'duotone', 'abacus' %>

Bear in mind that the brand icons only come in one style called brand(!) and the rest come in four variations but not all are available in the free collection. Find them all in the gallery

Note: Duotone style works just like all other icons, just use the 'duotone' style property.


If you get an error similar to this cannot load such file -- rexml/document (LoadError) you need to add rexml gem to your Gemfile


Issues and pull requests are more than welcome. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


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

Code of Conduct

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


A simple helper for Font-Awesome 5 using raw SVG and SVG-with-JS




Code of conduct





No packages published