Font Awesome 5 Rails

font_awesome5_rails provides the Font-Awesome5 web fonts, stylesheets and javascripts as a Rails engine for use with the asset pipeline and with backwards compatibility with font-awesome-rails gem.

This gem provides only Free icons from Font-Awesome.

Keep track of changes in Changelog.

Installation

Install as webfont with CSS
Install as SVG with JS
Install with webpack

Usage

Basic usage
Solid, Regular, Light, Brand icon types
Animations and data attributes
Layered and Stacked icons

Use as images
Use inline SVGs
FontAwesome 5 Pro icons
Release notes
Buy me a coffee

Installation

Now you have two options how to include FontAwesome 5 icons. First option is to use SVG and JS files which is recommended by FontAwesome team. However you can use icons as webfont with CSS but you will not be able to use new FA5 features as animations or layered_icons. Choose one installation option from above:

Check out the differences in here.

Add this line to your application's Gemfile:

gem 'font_awesome5_rails'

1. Install as webfont with CSS

In your application.css, include the css file:

 *= require font_awesome5_webfont

or if you prefer scss add this to your application.css.scss file:

@import 'font_awesome5_webfont';

2. Install as SVG with JS

In your application.css, include the css file:

 *= require font_awesome5

or if you prefer scss add this to your application.scss file:

@import 'font_awesome5.css'; //application.scss

If you're using .sass and having problem with loading, try to omit .css extenstion and import font as follows:

@import 'font_awesome5';

Check issue#57 for details.

In your application.js, include the javascript file:

#= require font_awesome5

3. Install with webpack

If you want to install Font Awesome with yarn or npm and still use helpers from this gem It's possible.

First add Font Awesome to your package.json.

$ yarn add @fortawesome/fontawesome-free

Next import font in your app/javascript/packs/application.js. You can find more about import in FA pages.

Now you have icons installed through webpack and still you can use fa_icon helpers.

4. Install webfont with CSS Bundling and Propshaft

To install the webfont on Rails 7+ with Propshaft and CSS Bundling (using Dart Sass), follow these instructions.

First, add Font Awesome 5 to your package.json:

$ npm install "@fortawesome/fontawesome-free@^5.0.0"

Then, copy the fonts to app/assets:

$ mkdir -p app/assets/fonts
$ cp -a node_modules/@fortawesome/fontawesome-free/webfonts app/assets/fonts/

Finally, add this to your app/assets/stylesheets/application.sass.scss:

$fa-font-path: "/webfonts";
@import "@fortawesome/fontawesome-free/scss/fontawesome";
@import "@fortawesome/fontawesome-free/scss/regular";
@import "@fortawesome/fontawesome-free/scss/solid";
@import "@fortawesome/fontawesome-free/scss/brands";
@import "@fortawesome/fontawesome-free/scss/v4-shims";

Usage

Gem provides FontAwesome icons through helper. In your views just call fa_icon.

Basic usage

fa_icon('camera-retro')
# => <i class="fas fa-camera-retro"></i>

fa_icon('camera-retro', style: 'color: Tomato')
# => <i class="fas fa-camera-retro" style="color:Tomato"></i>

fa_icon('camera-retro', class: 'my-class', text: 'Camera', size: '3x')
# => <i class="fas fa-camera-retro my-class fa-3x"></i>
# =>  <span>Camera</span>

fa_icon(:camera_retro, class: 'my-class')
# => <i class="fas fa-camera-retro my-class"></i>

fa_icon(:camera_retro, text: 'Camera', right: true)
# =>  <span class="fa5-text-r">Camera</span>
# => <i class="fas fa-camera-retro"></i>

Solid, Regular, Light, Brand, Duotone, Uploaded icon types

In Font Awesome 5 there are several different types of icons. In font_awesome5_rails gem default icon type is solid. If you want to use different icon style you can do this through type attribute.

Style	type:	type:
Solid	:fas	:solid
Regular	:far	:regular
Light	:fal	:light
Brand	:fab	:brand
Duotone	:fad	:duotone
Kit Uploaded	:fak	:uploaded

fa_icon('camera-retro', type: :solid) #Default
# => <i class="fas fa-camera-retro"></i>

fa_icon('camera-retro', type: :regular)
# => <i class="far fa-camera-retro"></i>

fa_icon('camera-retro', type: :light)
# => <i class="fal fa-camera-retro"></i>

fa_icon('camera-retro', type: :brand)
# => <i class="fab fa-camera-retro"></i>

fa_icon('camera-retro', type: :duotone)
# => <i class="fad fa-camera-retro"></i>

fa_icon('camera-retro', type: :fab)
# => <i class="fab fa-camera-retro"></i>

fa_icon('custom-uploaded', type: :fak)
# => <i class="fak fa-custom-uploaded"></i>

fa_icon('custom-uploaded', type: :uploaded)
# => <i class="fak fa-custom-uploaded"></i>

Each icon type has its own helper method so you don't need to provide the type attribute in every call. Which can be overridden, if it is provided.

far_icon('camera-retro')
# => <i class="far fa-camera-retro"></i>

far_icon('camera-retro', type: :fab)
# => <i class="fab fa-camera-retro"></i>

far_stacked_icon('camera', base: 'circle')
# => <span class="fa-stack">
# =>   <i class="far fa-circle fa-stack-2x"></i>
# =>   <i class="far fa-camera fa-stack-1x"></i>
# => </span>

far_stacked_icon('camera', base: 'circle', type: :fal)
# => <span class="fa-stack">
# =>   <i class="fal fa-circle fa-stack-2x"></i>
# =>   <i class="fal fa-camera fa-stack-1x"></i>
# => </span>

Animations and data attributes

FontAwesome 5 provides new animations and data attributes. Here are some examples how to use them:

fa_icon('camera-retro', animation: 'spin')
# => <i class="fas fa-camera-retro fa-spin"></i>

fa_icon('camera-retro', data: {'fa-transform': 'rotate-90'})
# => <i class="fas fa-camera-retro" data-fa-transform="rotate-90"></i>

In FontAwesome5 the text is right behind icon. For better readability text has defaultly set to padding-left: 5px;. If you want to override this setting, you can do that through .fa5-text class in css styles.

Layered and Stacked icons

FontAwesome 5 newly provides layered icons. For backward compatibility there were preserved fa_stacked_icon helper, but you can acomplish the same result with fa_layered_icon.

Layered icon examples

fa_layered_icon takes options and block of code that will be rendered inside.

Following fa_layered_icon examples are written in haml.

= fa_layered_icon do
  = fa_icon 'circle'
# => <span class="fa-layers fa-fw">
# =>   <i class="fas fa-circle"></i>
# => </span>

= fa_layered_icon style: 'background: MistyRose', size: '4x' do
  = fa_icon 'circle', style: 'color: Tomato'
  = fa_icon 'times', class: 'fa-inverse', data: { fa_transform: 'shrink-6' }
# => <div class="fa-4x">
# =>   <span class="fa-layers fa-fw" style="background: MistyRose">
# =>     <i class="fas fa-circle" style="color: Tomato"></i>
# =>     <i class="fas fa-times fa-inverse" data-fa-transform="shrink-6"></i>
# =>   </span>
# => </div>

= fa_layered_icon aligned: :false do
  = fa_icon 'circle'
  %span.fa-layers-text= "Text"
  %span.fa-layers-counter= "1,419"
# => <span class="fa-layers">
# =>   <i class="fas fa-circle"></i>
# =>   <span class="fa-layers-counter">1,419</span>
# => </span>

Stacked icon examples

For different base icon type you can use base_type option.

fa_stacked_icon('camera', base: 'circle')
# => <span class="fa-stack">
# =>   <i class="fas fa-circle fa-stack-2x"></i>
# =>   <i class="fas fa-camera fa-stack-1x"></i>
# => </span>

fa_stacked_icon('camera inverse', base: 'circle', type: :fas, class: 'my-class') #Default :fas is default type
# => <span class="fa-stack my-class">
# =>   <i class="fas fa-circle fa-stack-2x"></i>
# =>   <i class="fas fa-camera fa-inverse fa-stack-1x"></i>
# => </span>

fa_stacked_icon('camera', base: 'circle', reverse: true, text: 'Text!') #Default: reverse: false
# => <span class="fa-stack">
# =>   <i class="fas fa-circle fa-stack-1x"></i>
# =>   <i class="fas fa-camera fa-stack-2x"></i>
# => </span>Text!

fa_stacked_icon('camera', base: 'circle', type: :fas, base_type: :fab)
# => <span class="fa-stack">
# =>   <i class="fab fa-circle fa-stack-2x"></i>
# =>   <i class="fas fa-camera fa-stack-1x"></i>
# => </span>

fa_stacked_icon('camera', base: 'circle', type: :fas, base_type: :fab, base_options: { class: 'base' }, icon_options: { style: 'color: red' })
# => <span class="fa-stack">
# =>   <i class="fab fa-circle fa-stack-2x base"></i>
# =>   <i class="fas fa-camera fa-stack-1x" style="color: red"></i>
# => </span>

Use as images

From version 0.2.3 you can include icons as images in your views.

image_tag('fa5/solid/camera.svg')
image_tag('fa5/brand/facebook.svg')
image_tag('fa5/regular/bell.svg', width: '100px', class: 'my-img')

More examples can be found in specs.

More animation and data attributes can be found on FontAwesome documentation.

Use inline SVGs

You can also include icons as inline SVGs in your views directly, avoiding any JS entirely.

fa_inline_icon('camera') # defaults to solid
fa_inline_icon('camera', style: :solid)
fa_inline_icon('camera', class: 'my-svg')

There are also helpers for the various styles available:

fas_inline_icon('camera')
fab_inline_icon('facebook')
far_inline_icon('bell')

FontAwesome 5 Pro icons

Due to licence policy this gem pack only free FA5 icons. However fa_icon helper support all types of icons. If you purchased FA5 Pro icons and want to use helpers provided by this gem it's possible.

Add this gem to your Gemfile without including anything to application.css and application.js.
Create a Kit on Font Awesome.
Add = javascript_include_tag "//kit.fontawesome.com/[YOUR-KIT-ID].js" in the head of your layout(s).
You should now be able to use all FA5 Pro icons with helpers provided by this gem.

If you have any questions feel free to create a new issue.

Release notes

If you're upgrading from 0.3.x version to 0.4.x, you might need to change assets version in assets.rb, due to filename changes.

License

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

Font Awesome5 License.

Buy me a coffee

If you liked this gem, you can .

tomkr4l / font_awesome5_rails

readme