A JavaScript class you can use to determine whether a webfont got loaded, which font is being used by an element, or react to a webfont getting loaded (or failing to load).
Switch branches/tags
Nothing to show
View #16
Clone or download
#18 Compare This branch is even with stage-3.0.2.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib Change lang in options to eLang Jan 3, 2015
LICENSE.txt Updated the date on the license. Oct 12, 2014
README.md Update options documentation. Jan 3, 2015


#FontDetect Current version: 3.0.1

The FontDetect JavaScript library provides a singleton class that can tell you which font is being used for a particular element, or detect whether a font face has been loaded in your browser. It can also poll for the font being loaded and call a callback function when it loads - or another callback if it doesn't load within a timeout period.

##How to Use FontDetect The first step is to download the current version of fontdetect.zip and extract the script file (fontdetect.js or fontdetect.min.js). (Or clone this repo, of course.)

The script tag can be placed after the </body> if you wish.

<script type='text/javascript' src='/path/to/fontdetect.js'></script>

FontDetect provides three methods you can call. The first method, FontDetect.isFontLoaded, returns immediately with true or false depending on whether the specified font is present. This is most useful when you want to make sure an internal browser font is present:

#theContainerDiv {
    font-family: Trebuchet MS, Verdana, sans-serif;

if (!FontDetect.isFontLoaded('Trebuchet MS'))
{   // Assume we fell back to Verdana, so adjust the column width.
    $('#theContainerDiv').css('width', 500);

The FontDetect.whichFont method is more useful: It tells you exactly which font in the font stack is being used for a given element. In other words, it tells you what getComputedStyle(element).getPropertyValue("font-family") should return but doesn't. (Or in jQuery, what you would expect $(element).css("font-family") to return.)

#theContainerDiv {
    font-family: Oxygen, Verdana, Arial, sans-serif;

var wContainer;

switch (FontDetect.whichFont('#theContainerDiv'))
    case 'Oxygen':  wContainer = 500; break;
    case 'Verdana': wContainer = 480; break;
    default:        wContainer = 510; break;
$('#theContainerDiv').css('width', wContainer);

Finally, there's FontDetect.onFontLoaded. This waits asynchronously until the font gets loaded, or until a timeout period ends. Either way it calls a callback function that you specify:

    FontDetect.onFontLoaded ('MyCoolFont', onMyCoolFontLoaded, onItDidntLoad, {msTimeout: 3000});

function onMyCoolFontLoaded (fontname)
    alert (fontname + ' looks good!');

function onItDidntLoad (fontname)
    alert (fontname + ' didn\'t load within 3 seconds');

When you call FontDetect.onFontLoaded, you can specify how often to poll for the font (default is 100 ms, or 10 times/second); how long to try before giving up (default is 2 seconds), and the callback functions on successful or failed loads.

##Try it out

The original FontDetect project page has a nifty demo of the library in action. It's been updated to use the latest version of the library.

##API Reference ###isFontLoaded FontDetect.isFontLoaded (fontname)

This method determines whether a given font is loaded.

Required params Type Description
fontname string The name of the font to check for.
Returns Description
boolean true if the font has been loaded, else false if it didn't load or isn't provided by the browser.

###onFontLoaded FontDetect.onFontLoaded (fontname, onLoad, onFail, {msInterval: ms between polls , msTimeout: how long to keep polling} )

This method polls for the existence of a font in your browser. When a font gets loaded or a timeout period has passed, it will call the specified callback function(s).

Required params Type Description
fontname string The fontname of the webfont you want to detect.
onLoad function A function to be called when the font gets loaded. Use null if you don't have one.
onFail function A function to be called if the font doesn't get loaded within the timeout period. Use null if you don't have one.
You must specify at least one callback: onLoad or onFail. The callback functions take one parameter: the fontname that was detected.
Optional named params in { } Type Description
msInterval integer How many milliseconds between polling for the font. Default is 100ms.
msTimeout integer How many milliseconds to keep polling before giving up & calling the onFail callback. Default is 2000ms.
eLang string Which font language to use. Default = 'en'. Currently available languages are English (en) and Farsi (fa).

###whichFont FontDetect.whichFont (element)

This method determines which font, out of the fonts specified in the element's font stack, is actually being used to render it.

Required params Type Description
element string or object The element to examine. If jQuery is loaded we assume this is a jQuery selector string or object. If it's not loaded we expect this to be a DOM element.
Returns Description
string The name of the font that is being used for this element.

##Submitting code changes If you've fixed a bug or came up with a great addition to the API, I welcome your code submissions! To make things smoother, please follow these guidelines:

  • Create an Issue for the bug or feature you're submitting, if there isn't one already.
  • If someone is proposing a new feature or a change to the existing API, please chime in in the comments for that issue. It's important that the library evolves in a way that the userbase feels is useful and straightforward to use.
  • Submit to the latest Stage branch, not Master. This way we can test it & possibly integrate more than one bugfix or feature as a group.
  • The project's coding convention is for Allman-style bracing, where { and } are in the same column as their controlling statement.
  • Please use Hungarian notation for internal variables, and prefix any parameters with "p_". Use the existing code as a guide for what prefixes to use.
  • Don't assume that jQuery is loaded. If it's a jQuery-specific feature, at least make sure your code degrades gracefully if it's not there. You can test for jQuery with if (window.jQuery). (See _getCss for an example of how to handle this.)