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 yourfirst page in your Rails app, there are a couple of things that happen.
- Font Awesome will search for any
<i>elements and replace them with<svg>elements. - It will create a
MutationObserverthat watches for changes in the page todo future replacements.
When Turbolinks replaces the <body> of your page with new content afternavigation occurs, Font Awesome automatically reconnects this MutationObserverto the new content.
Here’s where the problem is: there is a flash where icons are missingbefore they quickly appear. This looks pretty nasty, but we can easily fix it.
Setting the mutateApproachconfiguration to sync (available in Version 5.8.0 or greater), provides a way to skip thisflash of missing icons by rendering them as soon as Turbolinks receives the newbody.
How To
We’re going to start by assuming that you’ve already installedTurbolinksand 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 haveincluded 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 %>
</html>
Using the asset pipeline
Another common way to install Font Awesome is to place the source files in thevendors/assets/javascripts directory and then modify theapp/assets/javascripts/application.js to include //= require fontawesome/all. Font Awesome will then get included in the applicationbundle 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 installFont Awesome.
Your installation may look like this, in which case we simply change the configusing 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 {
fa*github
} from '@fortawesome/free-brands-svg-icons'
library.add(
fa*github
)
dom.watch()
