# FontAwesome5Rails
[](https://travis-ci.org/tomkra/font_awesome5_rails)
[](http://hits.dwyl.io/tomkra/tomkra/font_awesome5_rails)
font_awesome5_rails provides the [Font-Awesome5](https://fontawesome.com/) web fonts, stylesheets and javascripts as a Rails engine for use with the asset pipeline and with backwards compatibility with [font-awesome-rails](https://github.com/bokmann/font-awesome-rails) gem.
This gem provides only Free icons from Font-Awesome.
## Table of Contents
**[Instalation](#instalation)**
**[Usage](#usage)**
- **[Basic usage](#basic-usage)**
- **[Solid, Regular, Light, Brand icon types](#solid-regular-light-brand-icon-types)**
- **[Animations and data attributes](#animations-and-data-attributes)**
- **[Layered and Stacked icons](#layered-and-stacked-icons)**
**[Use as images](#use-as-images)**
## 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:
### 1. Install as SVG with JS (recommended)
Add this line to your application's Gemfile:
```ruby
gem 'font_awesome5_rails'
```
In your `application.css`, include the css file:
```css
*= require font_awesome5
```
or if you prefer scss add this to your `application.css.scss` file:
```sass
@import 'font_awesome5';
```
In your `application.js`, include the javascript file:
```javascript
#= require font_awesome5
```
### 2. Install as webfont with CSS (old way)
In your `application.css`, include the css file:
```css
*= require font_awesome5_webfont
```
## Usage
Gem provides FontAwesome icons through helper. In your views just call `fa_icon`.
### Basic usage
```ruby
fa_icon('camera-retro')
# =>
fa_icon('camera-retro', style: 'color: Tomato')
# =>
fa_icon('camera-retro', class: 'my-class', text: 'Camera', size: '3x')
# =>
# => Camera
```
### Solid, Regular, Light, Brand 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 |
```ruby
fa_icon('camera-retro', type: :solid) #Default
# =>
fa_icon('camera-retro', type: :regular)
# =>
fa_icon('camera-retro', type: :light)
# =>
fa_icon('camera-retro', type: :brand)
# =>
fa_icon('camera-retro', type: :fab)
# =>
```
### Animations and data attributes
FontAwesome 5 provides new animations and data attributes. Here are some examples how to use them:
```ruby
fa_icon('camera-retro', animation: 'spin')
# =>
fa_icon('camera-retro', data: {'fa-transform': 'rotate-90'})
# =>
```
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```.
```ruby
= fa_layered_icon do
= fa_icon 'circle'
# =>
# =>
# =>
= 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' }
# =>
# =>
# =>
# =>
# =>
# =>
= fa_layered_icon aligned: :false do
= fa_icon 'circle'
%span.fa-layers-text= "Text"
%span.fa-layers-counter= "1,419"
# =>
# =>
# => 1,419
# =>
```
#### Stacked icon examples
For different base icon type you can use ```base_type``` option.
```ruby
fa_stacked_icon('camera', base: 'circle')
# =>
# =>
# =>
# =>
fa_stacked_icon('camera inverse', base: 'circle', type: :fas, class: 'my-class') #Default :fas is default type
# =>
# =>
# =>
# =>
fa_stacked_icon('camera', base: 'circle', reverse: true, text: 'Text!') #Default: reverse: false
# =>
# =>
# =>
# => Text!
fa_stacked_icon('camera', base: 'circle', type: :fas, base_type: :fab)
# =>
# =>
# =>
# =>
```
## Use as images
From version ```0.2.3``` you can include icons as images in your views.
```ruby
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](https://fontawesome.com/how-to-use/svg-with-js).
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
[Font Awesome5 License](https://fontawesome.com/license).