FA Rails

A quick helper for using FontAwesome icons in Rails.

Installation

This gem is just the code for using FontAwesome in your Rails applications.

You must still have your own FontAwesome Pro license, or install the Free package.

Add the following to config/application.rb:

require 'fa'

Local Files

Copy the complete js and css directories from the web download into the corresponding locations in your app, and ensure you correctly include all files.

FontAwesome CDN

You can also link into the FontAwesome CDN, in either of two ways:

Version-Specific Link

You can use this helper method in your layout:

FA::Link.new(version: 'v5.3.1', integrity: 'sha384-some-key-here').safe

Or, go to the FontAwesome How to Use page and copy the appropriate CDN link tag.

Be sure to also register each domain that will use this CDN link.

Free

<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.3.1/css/all.css" integrity="sha384-some-key-here" crossorigin="anonymous">

Pro

<link rel="stylesheet" href="https://pro.fontawesome.com/releases/v5.3.1/css/all.css" integrity="sha384-some-key-here" crossorigin="anonymous">

Kit Link

Use this helper method in your layout:

FA::Link.kit('kit-id')

Usage

The FA module contains three main subclasses: Icon, Span, and Layer. Argument formatting is consistent throughout.

Icon and Span are the units of this module. Both can be used individually. The first argument of each class's new method can be either a String/Symbol of the name of the FontAwesome icon, or a Hash containing the complete configuration for the object.

Layer is used to combine multiple units into a single end object. It takes advantage of the Hash input style on Icon and Span to allow it to accept a single configuration Array for the entire stack.

All three classes respond to two output methods: raw and safe.

raw outputs the formatted string directly
safe attempts to call .html_safe on the formatted string, if available

For convenience, each class also has a p method, which will create a new instance, and return its safe output.

There is also a Build class that exposes a DSL to construct a Layer.

Icon

A single FontAwesome icon.

Icon Arguments

fa #=> String / Symbol – OR Hash
options #=> Hash
  style: Symbol # One of [:solid, :regular, :light, :brands], default :solid
  mode: Symbol # One of [:sharp], default: nil
  size: Integer # Stepped scaling factor

  css: String # Arbitrary CSS classes, space-delimited
  raw_css: Hash # Arbitrary raw CSS, as a hash of attributes and values
  fa: String # Arbitrary FA classes, space-delimited – each is automatically prefixed with `fa-`
  title: String #=> Tooltip text
  grow: Integer #=> Transform value – amount to grow by
  shrink: Integer #=> Transform value – amount to shrink by
  rotate: Integer #=> Transform value – amount to rotate by
  up: Integer #=> Translation value upward
  down: Integer #=> Translation value downward
  left: Integer #=> Translation value leftward
  right: Integer #=> Translation value rightward

Span

A single FontAwesome span – counters or text labels – to be used in a Layer.

Span Arguments

fa #=> String / Symbol – one of [:counter, :text] – OR Hash
text #=> String
options #=> Hash
  position: Symbol # Indicator of which corner to display on – one of [:tr, :tl, :br, :bl]

  css: String # Arbitrary CSS classes, space-delimited
  raw_css: Hash # Arbitrary raw CSS, as a hash of attributes and values
  fa: String # Arbitrary FA classes, space-delimited – each is automatically prefixed with `fa-`
  title: String #=> Tooltip text
  grow: Integer #=> Transform value – amount to grow by
  shrink: Integer #=> Transform value – amount to shrink by
  rotate: Integer #=> Transform value – amount to rotate by
  up: Integer #=> Translation value upward
  down: Integer #=> Translation value downward
  left: Integer #=> Translation value leftward
  right: Integer #=> Translation value rightward

Layer

A stack of layered FontAwesome icons and spans.

Layer Arguments

icons #=> Array of Hashes of individual icon/span configurations
title #=> String – tooltip text
grow #=> Integer – additional global scaling factor added to all objects in the stack
css #=> String – arbitrary CSS classes, space-delimited, applied to the layer stack

Examples

# Fixed-width lock icon
FA::Icon.p('lock', fa: 'fw')
#=> "<i class='fas fa-fw fa-lock fa-1x' style='' data-fa-transform='' title=''></i>"

# Duotone fire-alt icon with swapped opacity
FA::Icon.p('fire-alt', fa: 'swap-opacity')
#=> "<i class='fas fa-swap-opacity fa-fire-alt fa-1x' style='' data-fa-transform='' title=''></i>"

# Duotone fire-alt icon with specified opacities
FA::Icon.p('fire-alt', style: :duotone, raw_css: { '--fa-primary-opacity' => '0.6', '--fa-secondary-opacity' => '0.4' })
#=> "<i class='fad fa-fire-alt fa-1x' style='--fa-primary-opacity: 0.4; --fa-secondary-opacity: 0.6;' data-fa-transform='' title=''></i>"

# Solid sharp house icon
FA::Icon.p('house', mode: :sharp)
#=> "<i class='fas fa-sharp fa-fire-alt fa-1x' style='' data-fa-transform='' title=''></i>"

# You can also use this simplified configuration option for adding styles
#   This is reforatted and merged into :raw_css
#   Accepts either snake_case symbols or spear-case strings as keys, and strings or symbols as values
#   This is the easiest way to add primary/secondary styles for duotone icons
FA::Icon.p('fire-alt', style: :duotone, fa_styles: { primary_opacity: '0.6', secondary_opacity: '0.4', primary_color: :green, secondary_color: '#DD2200' })
#=> "<i class='fad fa-fire-alt fa-1x' style='--fa-primary-opacity: 0.6; --fa-secondary-opacity: 0.4; --fa-primary-color: green; --fa-secondary-color: #DD2200;' data-fa-transform='' title=''></i>"

# Counter span, with value 5
FA::Span.p('counter', 5)
#=> "<span class='fa-layers-counter ' style='' data-fa-transform=''>5</span>"

# Gray envelope icon with red exclamation mark overlayed, with tooltip 'Invalid email address'
FA::Layer.p([{ name: 'envelope', options: { css: :gray } }, { name: 'exclamation', options: { css: :red } }], title: 'Invalid email address')
#=> "<span class='icon fa-layers fa-stack fa-fw ' title='Invalid email address'>" \
#   "<i class='fas fa-stack-1x gray fa-envelope fa-1x' style='' data-fa-transform='grow-0' title='Invalid email address'></i>" \
#   "<i class='fas fa-stack-1x red fa-exclamation fa-1x' style='' data-fa-transform='grow-0' title='Invalid email address'></i>" \
#   "</span>"

# Blue envelope with red counter on the top left corner, with value 7
FA::Layer.p([{ name: 'envelope', options: { css: :blue } }, { name: 'counter', text: 7, options: { css: :red, position: :tl } }])
#=> "<span class='icon fa-layers fa-stack fa-fw ' title=''>" \
#   "<i class='fas fa-stack-1x blue fa-envelope fa-1x' style='' data-fa-transform='grow-0' title=''></i>" \
#   "<span class='fa-stack-1x red fa-layers-counter fa-layers-top-left' style='' data-fa-transform='grow-0'>7</span>" \
#   "</span>"

# The same stack, but using the FA::Build DSL (with various syntaxes).
FA::Build.p do
  icon('envelope', css: 'blue')
  span('counter', 7, css: 'red', position: :tl)
end

FA::Build.p do |b|
  b.icon('envelope', css: 'blue')
  b.span('counter', 7, css: 'red', position: :tl)
end

FA::Build.new do |b|
  b.icon('envelope', css: 'blue')
  b.span('counter', 7, css: 'red', position: :tl)
end.safe