Skip to content
Font Awesome Docs: Version 5

Turbolinks

Font Awesome integrates well with the tool most often paired with Rails, to enable faster page performance by swapping out the <body> and merging the <head> of an HTML page

Integration Challenges

After you’ve installed the SVG with JS version of Font Awesome, and loaded your first page in your Rails app, there are a couple of things that happen.

  1. Font Awesome will search for any <i> elements and replace them with <svg> elements.
  2. It will create a MutationObserver that watches for changes in the page to do future replacements.

When Turbolinks replaces the <body> of your page with new content after navigation occurs, Font Awesome automatically reconnects this MutationObserver to the new content.

Here’s where the problem is: there is a flash where icons are missing before they quickly appear. This looks pretty nasty, but we can fix it easily.

Setting the mutateApproach configuration to sync (available in version 5.8.0 or greater), provides a way to skip this flash of missing icons by rendering them as soon as Turbolinks receives the new body.

With Rails

We’re going to start by assuming that you’ve already installed Turbolinks, and configured it in your Rails app.

Using our CDN or your own external hosting

If you’ve installed Font Awesome by modifying your Rails layout, you may have included a <script> tag.

Add data-mutate-approach="sync".

<!DOCTYPE html>
<html>
  <head>
    <title>My app</title>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>


    <%= stylesheet_link_tag    'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>
    <script src="https://use.fontawesome.com/releases/vVERSION/js/all.js" data-mutate-approach="sync"></script>
  </head>


  <body>
    <%= yield %>
  </body>
</html>

Using the asset pipeline

Another common way to install Font Awesome is to place the source files in the vendors/assets/javascripts directory and then modify the app/assets/javascripts/application.js to include //= require fontawesome/all. Font Awesome will then get included in the application bundle that your Rails layout already includes.

You can add a <script> tag in the layout to change the configuration.

<!DOCTYPE html>
<html>
  <head>
    <title>My app</title>
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>


    <script>
      FontAwesomeConfig = {
        mutateApproach: 'sync'
      }
    </script>


    <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>
  </head>


  <body>
    <%= yield %>
  </body>
</html>

But maybe the best way is to configure it directly in the application.js file.

// This is a manifest file that'll be compiled into application.js, which will include all the files
// listed below.
//
// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, or any plugin's
// vendor/assets/javascripts directory can be referenced here using a relative path.
//
// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
// compiled file. JavaScript code in this file should be added after the last require_* statement.
//
// Read Sprockets README (https://github.com/rails/sprockets#sprockets-directives) for details
// about supported directives.
//
//= require rails-ujs
//= require activestorage
//= require turbolinks
//= require fontawesome/all
//= require_tree .


FontAwesome.config.mutateApproach = 'sync'

Using Webpacker and @fortawesome/fontawesome-svg-core

You can subset icons using tree-shaking if you use Webpacker and NPM to install Font Awesome.

Your installation may look like this, in which case we simply change the config using the API.

import { config, library, dom } from '@fortawesome/fontawesome-svg-core'


# Change the config to fix the flicker
config.mutateApproach = 'sync'


# An example icon
import {
  faGithub
} from '@fortawesome/free-brands-svg-icons'


library.add(
  faGithub
)


dom.watch()