Skip to main content

Load web fonts with our JavaScript API

This page applies to:MindTouch Responsive

This article explains how to use MindTouch's JavaScript API wrapper for Google and Typekit's Web Font Loader JavaScript library.


MindTouch encourages site owners to use our Web Font JavaScript API instead of including Custom CSS Overrides @import statements to font providers such as

@import url(''); /* 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 will allow you to include web fonts in your content without slowing down web page loads.

Quick Start: Google Fonts

MindTouch already includes web fonts in its out-of-the-box MindTouch 4 and TCS experiences. 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 out of box experience mostly intact, we provide an interface to add additional fonts to the Google Fonts API request.


The syntax for Google Font Families is available here. You can include fonts with varying weights and styles. This 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('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's out of box fonts into a single web request for ideal performance.

Advanced: Custom Configuration

If you wish to completely remove MindTouch's out of box Google Fonts, and replace them with different ones from Google, Typekit,, Fontdeck, or your own custom @font-face CSS, you can override the Web Font Loader configuration directly.

    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

If you use plan to use custom @font-face CSS, use must specify test strings. For this example, we will use FontAwesome and load from that source.

    custom: {
        families: ['FontAwesome'],
        urls: ['//'],
        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.

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.

Preventing 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, by some chance, 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

If you want to programmatically add or remove fonts to hide and display, you can use the Web Font addFontElements and removeFontElements methods. Suppose in your page header you have 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 elements while the font is loading. On the other hand 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.