Skip to content
Font Awesome Docs

Rails with Turbolinks

Font Awesome integrates well with Rails and Turbolinks, especially if you use Web Fonts. But if you’re using SVG + JS, you’ll need to make a few adjustments.

We’ll cover what to do when you encounter visual glitches caused by MutationObserver, and how to install Font Awesome, whether you use a Kit or Host Font Awesome yourself, and more!

What’s the Challenge?

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 easily fix it.

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.

How To

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

Using Your Application Configuration

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.
//
//= require rails-ujs
//= require activestorage
//= require turbolinks
//= require fontawesome/all
//= require_tree .


FontAwesome.config.mutateApproach = 'sync'

Using a Kit 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="<your-kit-code>" 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>

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()