webfontloader
Cross-browser JavaScript library that gives you a single, consistent API for loading @font-face web fonts from any provider.
Repository Health
Technical Analysis
Web Font Loader is a small, dependency-free JavaScript library that gives you deterministic control over how custom fonts load and render in the browser. It wraps Google Fonts, Typekit, Fontdeck, Monotype, and self-hosted @font-face declarations behind one consistent WebFont.load() API, exposing loading/active/inactive lifecycle events and matching CSS classes so pages can avoid invisible text and flash-of-unstyled-text issues regardless of which font provider they use.
Co-developed by Google and Typekit, it detects font readiness either through the native CSS Font Loading API or, on older browsers, by measuring fallback-glyph widths with an offscreen ruler element — a technique built before document.fonts existed. It ships as an npm package, a Ruby gem, and a Bower component, with its browser bundle compiled via Google’s Closure Compiler.
What You Get
- A single
WebFont.load()entry point supporting Google Fonts, Typekit, Fontdeck, Monotype, and self-hostedcustomfont sources - Loading/active/inactive JS events plus matching CSS classes on the
<html>element for FOUT-safe styling - Automatic native-vs-fallback font-detection strategy selection per browser
- Distributable builds for npm (CommonJS/AMD/global), Bower, and RubyGems
Common Use Cases
- Preventing invisible or flash-of-unstyled text on font-heavy marketing sites
- Coordinating multiple font providers under one loading contract
- Gating layout-dependent CSS until custom fonts are confirmed active
- Loading fonts into same-origin iframes via the
contextoption
Under The Hood
Architecture
A core webfont.WebFont class orchestrates pluggable provider modules registered through a FontModuleLoader (Google, Typekit, Fontdeck, Monotype, and a generic Custom module for self-hosted fonts), then hands the resulting font list to a FontWatcher that spins up one FontWatchRunner (glyph-measurement fallback) or NativeFontWatchRunner (CSS Font Loading API) per font and aggregates their results through an EventDispatcher that fires the public loading/active/inactive callbacks and toggles CSS classes on the document root. It’s a clean strategy-pattern split between font-source registration and font-load detection, though it’s built on the Google Closure Compiler’s goog.provide/goog.scope module system rather than ES modules, and per-provider bundles are produced by selectively compiling in only the modules a build target needs.
Tech Stack
Pure vanilla ES5 JavaScript with zero runtime dependencies, annotated with Closure Compiler JSDoc types for advanced-mode-safe minification. The distributable webfontloader.js and per-provider bundles are built by a Ruby Rakefile invoking the bundled Closure Compiler jar (tools/compiler/compiler.jar); the library is published in parallel as an npm CommonJS/AMD/global UMD module, a Bower component, and a RubyGem (webfontloader.gemspec) with an accompanying Sinatra-style Ruby demo server under lib/webfontloader/demo.
Code Quality
An extensive Jasmine spec suite (spec/core/*, spec/modules/*) covers the DOM helper, font ruler measurement, both watch-runner implementations, and every provider module, executed cross-browser via PhantomJS and BrowserStack through Travis CI. The code favors explicit handling of browser quirks — such as detecting the WebKit fallback-font bug or gating the native loader behind Firefox/Safari version checks — over silently ignoring them, and follows a consistent private-member (_ suffix) and namespacing convention throughout. There is no linter or formatter configuration, and the project has had no recent commits or releases, so any modern browser regressions would go unpatched.
API Design
The entire surface area is a single WebFont.load(configuration) call that unifies fundamentally different font-loading mechanisms — a Google Fonts API request, a Typekit kit ID, a Fontdeck project ID, or arbitrary self-hosted @font-face rules — behind one declarative object and one event/CSS-class contract, which keeps integration code identical regardless of font source. Its most distinctive technical choice is the offscreen FontRuler glyph-width-measurement fallback for browsers without the CSS Font Loading API, a workaround that was genuinely useful at the library’s peak but has been largely superseded by native document.fonts.ready support in modern browsers.
Used by 2 apps in this directory
Onlook
Design Tools · AI Design Tools
An open-source, AI-first visual editor that lets designers and developers build, style, and deploy React apps directly in code — no handoff required.
TinaCMS
CMS
An open-source, Git-backed headless CMS that gives editors a live visual editing UI over Markdown, MDX, JSON, and YAML content while developers keep everything in version control.
