ffontsloader

Demo: https://murdad.github.io/ffontsloader/demo/index.html

🚀 Faster Fonts Loader

Fonts Loader gives you total control over the fonts loading via @font-face. You're getting a common interface to load fonts regardless of source. Some popular online libraries are included, like Google Font API. You can also load fonts from self-hosted sources and control them via FontsLoader events tool.

Compatibility with Web Font Loader

Fonts Loader is compatible with Web Font Loader. Interface is same, just replace WebFont.load() with FontsLoader.load().

Get Started

To use the Fonts Loader library, just include it in your page and tell it which fonts to load. For example, you could load fonts from Google Fonts using the Fonts Loader hosted on Google Hosted Libraries using the following code.

<script src="https://murdad.github.io/ffontsloader/dist/fontsloader.js"></script>
<script>
  FontsLoader.load({
    google: {
      families: ['Droid Sans', 'Droid Serif']
    }
  });
</script>

It is also possible to load fonts asynchronosly, here is an example:

<script src="https://murdad.github.io/ffontsloader/dist/fontsloader.js"></script>
<script>
    const { FontsLoader } = window;
    (async function() {
        await FontsLoader.load({
            google: {
                families: ['Tangerine', 'IBM Plex Sans Thai Looped:300,700:latin,greek']
            }
        });
    })();
</script>

Or using npm

$ npm i --save ffontsloader

Configuration

The Fonts Loader configuration is passed directly to the FontsLoader.load method. It defines which fonts to load from each web font provider and gives you the option to specify callbacks for certain events.

Events

Fonts Loader provides an event system that developers can hook into. It gives you notifications of the font loading sequence in both CSS and JavaScript.

• loading - This event is triggered when all fonts have been requested.
• active - This event is triggered when the fonts have rendered.
• inactive - This event is triggered when the browser does not support linked fonts or if none of the fonts could be loaded.
• fontloading - This event is triggered once for each font that's loaded.
• fontactive - This event is triggered once for each font that renders.
• fontinactive - This event is triggered if the font can't be loaded.

CSS events are implemented as classes on the html element. The following classes are set on the html element:

.wf-loading
.wf-active
.wf-inactive
.wf-<familyname>-<fvd>-loading
.wf-<familyname>-<fvd>-active
.wf-<familyname>-<fvd>-inactive

The <familyname> placeholder will be replaced by a sanitized version of the name of each font family. Spaces and underscores are removed from the name, and all characters are converted to lower case. For example, Droid Sans becomes droidsans. The <fvd> placeholder is a Font Variation Description. Put simply, it's a shorthand for describing the style and weight of a particular font. Here are a few examples:

/* n4 */
@font-face { font-style: normal; font-weight: normal; }

/* i7 */
@font-face { font-style: italic; font-weight: bold; }

Keep in mind that font-weight: normal maps to font-weight: 400 and font-weight: bold maps to font-weight: 700. If no style/weight is specified, the default n4 (font-style: normal; font-weight: normal;) will be used.

If fonts are loaded multiple times on a single page, the CSS classes continue to update to reflect the current state of the page. The global wf-loading class is applied whenever fonts are being requested (even if other fonts are already active or inactive). The wf-inactive class is applied only if none of the fonts on the page have rendered. Otherwise, the wf-active class is applied (even if some fonts are inactive).

JavaScript events are implemented as callback functions on the configuration object.

FontsLoader.load({
  loading: function() {},
  active: function() {},
  inactive: function() {},
  fontloading: function(familyName, fvd) {},
  fontactive: function(familyName, fvd) {},
  fontinactive: function(familyName, fvd) {},
});

The fontloading, fontactive and fontinactive callbacks are passed the family name and font variation description of the font that concerns the event.

It is possible to disable setting classes on the HTML element by setting the classes configuration parameter to false (defaults to true).

FontsLoader.load({
  classes: false,
});

You can also disable font events (callbacks) by setting the events parameter to false (defaults to true).

FontsLoader.load({
  events: false,
});

If both events and classes are disabled, the Fonts Loader does not perform font watching and only acts as a way to insert @font-face rules in the document.

Timeouts

Since the Internet is not 100% reliable, it's possible that a font will fail to load. The fontinactive event will be triggered after 5 seconds if the font fails to render. If at least one font successfully renders, the active event will be triggered, else the inactive event will be triggered.

You can change the default timeout by using the timeout option on the configuration object.

NOTE: if FontFace callback is triggered that all fonts have been loaded, the timeout would be ignored.

FontsLoader.load({
  google: {
    families: ['Droid Sans'],
  },
  timeout: 2000, // Set the timeout to two seconds
});

The timeout value should be in milliseconds, and defaults to 3000 milliseconds (3 seconds) if not supplied.

Custom

To load fonts from any external stylesheet, use the custom module. Here you'll need to specify the font family names you're trying to load, and optionally the url of the stylesheet that provides the @font-face declarations for those fonts.

You can specify a specific font variation or set of variations to load and watch by appending the variations separated by commas to the family name separated by a colon. Variations are specified using FVD notation.

FontsLoader.load({
  custom: {
    families: ['My Font', 'My Other Font:n4,i4,n7'],
    urls: ['/fonts.css'],
  },
});

Or you can also load families as objects

FontsLoader.load({
  custom: {
    families: [
      {
        name: 'My Font',
        url: '/font.css',
      },
      {
        name: 'My Other Font',
        url: '/other-font.css',
      },
    ],
  },
});

In this example, the fonts.css file might look something like this:

@font-face {
  font-family: 'My Font';
  src: ...;
}
@font-face {
  font-family: 'My Other Font';
  font-style: normal;
  font-weight: normal; /* or 400 */
  src: ...;
}
@font-face {
  font-family: 'My Other Font';
  font-style: italic;
  font-weight: normal; /* or 400 */
  src: ...;
}
@font-face {
  font-family: 'My Other Font';
  font-style: normal;
  font-weight: bold; /* or 700 */
  src: ...;
}

TODO

• [ ] Add more tests
• [ ] Increase coverage
• [ ] Rewrite README.md
• [ ] Update demos
• [ ] Implement native loader for custom fonts
• [ ] Add React, Angular and Vue examples
• [ ] Add more font API sources
• [ ] Use Google API v2