Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tomkr4l/font_awesome5_rails
font_awesome_5_rails is font awesome 5 gem bundled for rails asset pipeline
https://github.com/tomkr4l/font_awesome5_rails
List: font_awesome5_rails
font-awesome rails
Last synced: 13 days ago
JSON representation
font_awesome_5_rails is font awesome 5 gem bundled for rails asset pipeline
- Host: GitHub
- URL: https://github.com/tomkr4l/font_awesome5_rails
- Owner: tomkr4l
- License: mit
- Created: 2018-02-25T22:04:01.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-08-04T17:58:45.000Z (over 2 years ago)
- Last Synced: 2024-10-09T09:01:31.173Z (about 1 month ago)
- Topics: font-awesome, rails
- Language: SCSS
- Homepage: https://fontawesome.com/
- Size: 12.7 MB
- Stars: 158
- Watchers: 2
- Forks: 25
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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)**
- **[Install as webfont with CSS](#install-as-webfont-with-css)**
- **[Install as SVG with JS](#install-as-SVG-with-JS)**
- **[Install with webpack](#install-with-webpack)**
**[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)**
**[Use inline SVGs](#use-inline-svgs)**
**[FontAwesome 5 Pro icons](#fontawesome-5-pro-icons)**
**[Release notes](#release-notes)**
**[Buy me a coffee](#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](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:
```scss
@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:
```scss
@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:
```scss
@import 'font_awesome5';
```
Check [issue#57](https://github.com/tomkra/font_awesome5_rails/issues/57) for details.
In your `application.js`, include the javascript file:
```javascript
#= 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```.
```shell
$ yarn add @fortawesome/fontawesome-free
```
Next import font in your ```app/javascript/packs/application.js```. You can find more about import in [FA pages](https://fontawesome.com/how-to-use/with-the-api/setup/importing-icons).
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```:
```shell
$ npm install "@fortawesome/fontawesome-free@^5.0.0"
```
Then, copy the fonts to `app/assets`:
```shell
$ 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`:
```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";
```
[CSS Bundling]: https://github.com/rails/cssbundling-rails
[Propshaft]: https://github.com/rails/propshaft
## 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')
# =>
fa_icon(:camera_retro, text: 'Camera', right: true)
# => Camera
# =>
```
### 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|
```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: :duotone)
# =>
fa_icon('camera-retro', type: :fab)
# =>
fa_icon('custom-uploaded', type: :fak)
# =>
fa_icon('custom-uploaded', type: :uploaded)
# =>
```
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.
```ruby
far_icon('camera-retro')
# =>
far_icon('camera-retro', type: :fab)
# =>
far_stacked_icon('camera', base: 'circle')
# =>
# =>
# =>
# =>
far_stacked_icon('camera', base: 'circle', type: :fal)
# =>
# =>
# =>
# =>
```
### 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)
# =>
# =>
# =>
# =>
fa_stacked_icon('camera', base: 'circle', type: :fas, base_type: :fab, base_options: { class: 'base' }, icon_options: { style: 'color: red' })
# =>
# =>
# =>
# =>
```
## 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).
## Use inline SVGs
You can also include icons as inline SVGs in your views directly, avoiding any JS entirely.
```ruby
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:
```ruby
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.
1. Add this gem to your ```Gemfile``` without including anything to ```application.css``` and ```application.js```.
2. Create a [Kit](https://fontawesome.com/kits) on Font Awesome.
3. Add `= javascript_include_tag "//kit.fontawesome.com/[YOUR-KIT-ID].js"` in the head of your layout(s).
4. 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](http://opensource.org/licenses/MIT).
[Font Awesome5 License](https://fontawesome.com/license).
### Buy me a coffee
If you liked this gem, you can
.