SVG Async Loading

Using JavaScript to load SVG icons provides a non-blocking mechanism to show icons on a page. If you want more fine-grained control over how icons appear you can use CSS and our loading events.

While async icon loading allows the page to render sooner it can also make page layouts shift.

You can avoid icons loading and shifting your layout or text by leveraging some classes that are added to the <html> tag as part of the loading operations that the JavaScript engine performs.

<html>
  <head></head>
  <body>
    <i class="fas fa-user"></i> My User

    <script defer src="/static/fontawesome/fontawesome-all.js"></script>
  </body>
</html>

As the browser begins to search for icons the <html> tag will contain fontawesome-i2svg-pending. (i2svg is our abbreviation for converting “i tags to SVG”)

<html class="fontawesome-i2svg-pending">
  ...
</html>

After icon replacement has completed the pending class will be replaced with fontawesome-i2svg-complete and the fontawesome-i2svg-active will be added as well.

<html class="fontawesome-i2svg-active fontawesome-i2svg-complete">
  ...
</html>

The fontawesome-i2svg-active class will remain once the first successful loading of icons has finished. However, if another batch of icons is loaded the complete will switch to pending again.

<html class="fontawesome-i2svg-active fontawesome-i2svg-pending">
  ...
</html>

And again once the icon replacement occurs we get back to our complete event.

<html class="fontawesome-i2svg-active fontawesome-i2svg-complete">
  ...
</html>

This allows us to do some interesting things with CSS. For example we could hide the <body> until the icons were loaded.

body {
  display: none;
}

.fontawesome-i2svg-active body {
  display: initial;
}

Or only show certain sections once icons are replaced.

<main>
  <div>Main section that always shows</div>

  <div class="wait-for-icons">
    <i class="fas fa-camera"></i> I like cameras
  </div>
</main>

.wait-for-icons {
  display: none;
}

.fontawesome-i2svg-active .wait-for-icons {
  display: initial;
}