# Font Awesome 5 Rails
[](https://badge.fury.io/rb/font_awesome5_rails)
[](https://github.com/tomkra/font_awesome5_rails/blob/master/lib/font_awesome5_rails/version.rb)
[](https://travis-ci.org/tomkra/font_awesome5_rails)
[](http://hrits.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.
Keep track of changes in [Changelog](https://github.com/tomkra/font_awesome5_rails/blob/master/CHANGELOG.md).
## Table of Contents
**[Installation](#installation)**
**[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)**
**[FontAwesome 5 Pro icons](#fontawesome-5-pro-icons)**
**[Release notes](#release-notes)**
## 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 ou the differences in [here](https://fontawesome.com/how-to-use/on-the-web/setup/getting-started?using=svg-with-js&explain=using).
Add this line to your application's Gemfile:
```ruby
gem 'font_awesome5_rails'
```
### 1. Install as webfont with CSS
In your `application.css`, include the css file:
```css
*= require font_awesome5_webfont
```
or if you prefer scss add this to your `application.css.scss` file:
```sass
@import 'font_awesome5_webfont';
```
### 2. Install as SVG with JS
In your `application.css`, include the css file:
```css
*= require font_awesome5
```
or if you prefer scss add this to your `application.scss` file:
```sass
@import 'font_awesome5.css';
```
In your `application.js`, include the javascript file:
```javascript
#= require font_awesome5
```
## 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
fa_icon(:camera_retro, class: 'my-class')
# =>
```
### 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).
## 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 buyed FA5 Pro icons and want to use helpers provided by this gem it's possible.
1. Add this gem to your ```Gemfile``` without including anything to ```application.css``` and ```application.js```.
2. Download your FA5 pro icons and unpack them.
3. Now you will have to manualy include all FA5 files you want to use to your ```/assets``` folder.
4. If you're using ```svg``` files do not forget to include ```*.svg``` in your ```assets.rb``` file.
5. 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 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](http://opensource.org/licenses/MIT).
[Font Awesome5 License](https://fontawesome.com/license).