DOCSEARCHbyAlgolia
Submit Docs

Web Font Loader

repository·master·Indexed 27 days ago

https://github.com/typekit/webfontloader

A JavaScript library providing a unified interface for loading web fonts from providers including Google Fonts, Typekit, Fontdeck, and Fonts.com (monotype), as well as custom external stylesheets. It offers standardized CSS classes and JavaScript events to manage the loading experience and prevent Flash of Unstyled Text (FOUT).

Tokens
2.8K
Snippets
10
Records
17
Agent score
44%

What's inside webfontloader

  1. Load fonts asynchronously

    master

    To avoid blocking page rendering, you can load the Web Font Loader script asynchronously. When using this method, you must define the global WebFontConfig object before the script is loaded.

    Note: Asynchronous loading may cause a Flash of Unstyled Text (FOUT) because the page might render before the fonts are ready.

    <script>
   WebFontConfig = {
      typekit: { id: 'xxxxxx' }
   };

   (function(d) {
      var wf = d.createElement('script'), s = d.scripts[0];
      wf.src = 'https://ajax.googleapis.com/ajax/libs/webfont/1.6.26/webfont.js';
      wf.async = true;
      s.parentNode.insertBefore(wf, s);
   })(document);
</script>

  2. Install Web Font Loader

    master

    You can include Web Font Loader in your project via CDN or by installing it as an npm module.

    Via CDN

    Include the script tag in your HTML. For production, it is recommended to use an explicit version number for performance and caching stability.

    Via npm

    Install the package using npm and require it in your CommonJS environment.

    npm install webfontloader

  3. Configure Web Font Loader events and options

    master

    Configuration can be provided via a global WebFontConfig object or passed directly to WebFont.load().

    Available Configuration Keys

    • google: Object containing families array for Google Fonts.
    • typekit: Object containing id for Typekit.
    • classes: Boolean. Set to false to disable adding CSS classes to the html element (defaults to true).
    • events: Boolean. Set to false to disable JavaScript callback functions (defaults to true).
    • timeout: Number. The timeout in milliseconds before triggering the fontinactive event (defaults to 3000).
    • context: Window object. Used for managing fonts across same-origin iframes.

  4. Load web fonts with WebFont.load()

    master

    The primary way to use Web Font Loader is by calling WebFont.load(). This method accepts a configuration object that specifies the font provider (e.g., google, typekit, fontdeck, monotype, or custom), the font families to load, and event handlers for font loading states.

    Supported font providers include:

    • google: Google Fonts
    • typekit: Adobe Typekit
    • fontdeck: Fontdeck
    • monotype: Fonts.com
    • custom: Arbitrary URLs or Fontdeck-style modules

    You can also configure events to listen for specific lifecycle stages and classes to toggle CSS classes on the <html> element.

  6. Use the Fonts.com (monotype) module

    master

    To use Fonts.com web fonts, use the monotype module with your Project ID.

    • projectId: Your Fonts.com Project ID.
    • version: (Optional) A value used to flush the CDN cache.
    • loadAllFonts: (Optional) A boolean. If true, loads all project fonts. If false (default), only loads fonts used on the page.
    WebFontConfig = {
  monotype: {
    projectId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    version: 12345,
    loadAllFonts: true
  }
};

  7. Use the Google module

    master

    To use Google's Font API, use the google module.

    • families: An array of font family names. You can specify weights (e.g., Open Sans:300,700) and subsets (e.g., Open Sans:300,700:latin,greek) by appending them to the family name with colons. Note: The Google module does not support FVD notation used in the custom module.
    • text: (Optional) A string used for character subsetting to improve performance.
    WebFontConfig = {
  google: {
    families: ['Open Sans Condensed:300,700:latin,greek'],
    text: 'abcdefghijklmnopqrstuvwxyz!'
  }
};

  8. Use Web Font Loader JavaScript callbacks

    master

    You can hook into the font loading lifecycle using callback functions defined in your configuration object.

    Callback Signatures

    • loading(): Triggered when all fonts have been requested.
    • active(): Triggered when fonts have rendered.
    • inactive(): Triggered if no fonts could be loaded or browser doesn't support them.
    • fontloading(familyName, fvd): Triggered once for each font that is loaded.
    • fontactive(familyName, fvd): Triggered once for each font that renders.
    • fontinactive(familyName, fvd): Triggered if a specific font fails to load.
    WebFontConfig = {
  loading: function() {},
  active: function() {},
  inactive: function() {},
  fontloading: function(familyName, fvd) {},
  fontactive: function(familyName, fvd) {},
  fontinactive: function(familyName, fvd) {}
};

  9. Use the Adobe Edge Web Fonts module

    master

    To load fonts from Adobe Edge Web Fonts, use the typekit module. Provide a semicolon-separated list of font IDs in the id parameter and set the api parameter to //use.edgefonts.net.

    WebFontConfig = {
  typekit: {
    id: 'adamina;advent-pro',
    api: '//use.edgefonts.net'
  }
};

  10. Use the Custom module for external stylesheets

    master

    The custom module allows you to load fonts from any external stylesheet.

    • families: An array of font family names. You can specify variations using FVD notation (e.g., Family:n4,i4) by appending them to the name with a colon.
    • urls: (Optional) An array of URLs to stylesheets containing the @font-face declarations.
    • testStrings: (Optional) A mapping of font family names to specific character strings used to detect if the font has loaded. This is useful for custom subsets or private use unicode areas. If not specified, the default is BESbswy.
    WebFontConfig = {
  custom: {
    families: ['My Font', 'My Other Font:n4,i4,n7'],
    urls: ['/fonts.css'],
    testStrings: {
      'My Font': '\uE003\uE005'
    }
  }
};

  12. Use the Typekit module

    master

    To use Typekit, provide your Kit ID in the typekit module configuration.

    Note: Typekit's own JavaScript is built using Web Font Loader and provides the same event functionality. Use Typekit's embed codes directly unless you need to load fonts from other providers on the same page.

    WebFontConfig = {
  typekit: {
    id: 'xxxxxx'
  }
};