Skip to main content
MindTouch Success Center

Web font loader via JavaScript API

Use the MindTouch JavaScript API wrapper for Google and Typekit's Web Font Loader JavaScript library.

We recommend site owners use our Web Font JavaScript API instead of including Custom CSS Overrides @import statements to font providers. For example:

@import url('http://fonts.googleapis.com/css?family=PT+Sans'); /* BAD! */

Downloading @font-face CSS and web fonts in this manner causes the web browser to block web page loading so that it can resolve and download these assets from a third party. Considering Google's reliable infrastructure, we assume these requests are handled quickly and correctly, but it is generally bad practice to block web page loading to fetch third party assets (even Google!). This JavaScript API allows you to include web fonts in your content without slowing down web page loads.

Quick start: Google fonts

MindTouch includes web fonts as part of standard functionality. We use Google Fonts API as our provider, and leverage our own Web Fonts JavaScript API to load fonts. For basic branding overrides, where you wish to keep the default experience mostly intact, we provide an interface to add additional fonts to the Google Fonts API request.

Deki.Fonts.addGoogleFontFamily('Roboto:r,700');

The syntax for Google Font Families is available here. You can include fonts with varying weights and styles. This example will add Roboto with regular style and a 700 weight style. The addGoogleFontFamily function can be called multiple times to add more than one font.

Deki.Fonts.addGoogleFontFamily('Ubuntu');
Deki.Fonts.addGoogleFontFamily('Droid Serif:r,b,i');

Since this is a JavaScript API, you can include your call in a preformatted JavaScript code block in your custom site header. This will ensure that your fonts are loaded on every web page. In addition, you can add the code into a single page's content, to load the font for that page only.

Your fonts are combined with MindTouch default fonts into a single web request for ideal performance.

Advanced: custom configuration

To completely remove MindTouch default Google Fonts and replace them with different ones from Google, Typekit, Fonts.com, Fontdeck, or your own custom @font-face CSS, you can override the Web Font Loader configuration directly.

Deki.Fonts.setConfig({
    monotype: {
         projectId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
         version: 12345
    }
});

This option assumes you are very familiar with Web Font Loader modules and configuration.

Custom font face

To use custom @font-face CSS, specify test strings. For this example, we will use FontAwesome and load from that source.

Deki.Fonts.setConfig({
    custom: {
        families: ['FontAwesome'],
        urls: ['//netdna.bootstrapcdn.com/font-awesome/4.1.0/css/font-awesome.min.css'],
        testStrings: {
            'FontAwesome': '\uf083\uf015'
        }
    }
});
/* font-awesome.min.css */
@font-face {
  font-family: 'FontAwesome';
  src: url('../fonts/fontawesome-webfont.eot?v=4.1.0');
  src: url('../fonts/fontawesome-webfont.eot?#iefix&v=4.1.0') format('embedded-opentype'), url('../fonts/fontawesome-webfont.woff?v=4.1.0') format('woff'), url('../fonts/fontawesome-webfont.ttf?v=4.1.0') format('truetype'), url('../fonts/fontawesome-webfont.svg?v=4.1.0#fontawesomeregular') format('svg');
  font-weight: normal;
  font-style: normal;
}

/* glyphs */
.fa-camera-retro:before {
   content: "\f083";
}
.fa-home:before {
   content: "\f015";
}
families An array of font-family names found in the CSS @font-face declaration
urls An array of URLS where the CSS containing the @font-face declaration can be downloaded.  Notice that schema-less protocol (//) is used.
testStrings

Test content, per font-family, that will verify whether or not the font has been successfully loaded. This is more commonly used for glyphs or custom subsets in the private use unicode area such as Icon Fonts.

The official Web Font Loader documentation includes further details regarding custom web font loading.

Prevent Flash of unstyled text

When using the Javascript Web Font API, the page asynchronously loads the font to avoid blocking the rest of the page load. This might cause the rest of the page to render before the font is loaded and applied to the text styled with the font. This is also known as Flash of Unstyled Text or FOUT.

Our Javascript Web Font API battles FOUT by using the callbacks provided in the Web Font loader. We set the visibility of a user-supplied list of elements to hidden when the fonts were being loaded. Once the font had loaded, we set the elements visibility to visible. If the fonts fail to load, the elements will still show after a certain amount of time.

To specify the elements you want to hide use the setFontElement helper method of our own Web Font API. To do this, insert a preformatted JavaScript code block of your page header, or a single page's content.

The setFontElement helper accepts an array jQuery selectors as its value.

Deki.Fonts.setFontElements(['a.title', '#main-text a', '.description label']);

If using the cedar engine, if you do not declare the font elements to hide, it will default to this list:

[ ".product-links .title a", "p", "h1", "h2", "h3", "h4", "h5", "h6", ".sub-guides .title","pre.script-css", ".code", ".pre", "fieldset legend" ]

Adding and removing elements

To programmatically add or remove fonts to hide and display, use the Web Font addFontElements and removeFontElements methods. For example, if your page header contains the following code:

Deki.Fonts.setFontElements(['a', 'p', 'h1']);

And inside a page you want to add elements to that list, you can do it by:

Deki.Fonts.addFontElements(['h3', 'h4', '.span .link']);

This will result in hiding the <a>, <p>, <h1>, <h3>, <h4> and <.span.link> elements while the font is loading. You can also remove elements from a list, using the page header example above:

Deki.Fonts.removeFontElements(['a', 'h1']);

This will result in hiding the <p> elements while the font is loading.

  • Was this article helpful?