CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-fontfaceobserver

Detect if web fonts are available

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

FontFaceObserver

FontFaceObserver is a lightweight web font loading monitor and detector that efficiently tracks when @font-face fonts become available in the browser. It provides a Promise-based API for monitoring font loading events, supports custom test strings for non-Latin fonts, and configurable timeouts.

Package Information

  • Package Name: fontfaceobserver
  • Package Type: npm
  • Language: JavaScript (compatible with TypeScript)
  • Installation: npm install fontfaceobserver

Core Imports

import FontFaceObserver from "fontfaceobserver";

For CommonJS:

const FontFaceObserver = require("fontfaceobserver");

For browser (global):

// FontFaceObserver is available as window.FontFaceObserver
const FontFaceObserver = window.FontFaceObserver;

Basic Usage

import FontFaceObserver from "fontfaceobserver";

// Create observer for a font family
const font = new FontFaceObserver('My Family', {
  weight: 400,
  style: 'normal'
});

// Monitor font loading
font.load().then(function () {
  console.log('Font is available');
  document.documentElement.className += " fonts-loaded";
}, function () {
  console.log('Font failed to load');
});

// Custom test string for non-Latin fonts
const chineseFont = new FontFaceObserver('Chinese Font');
chineseFont.load('中国').then(function () {
  console.log('Chinese font loaded');
});

// Custom timeout (default is 3000ms)
font.load(null, 5000).then(function () {
  console.log('Font loaded within 5 seconds');
});

Architecture

FontFaceObserver uses different detection mechanisms based on browser capabilities:

  • Native Font Loading API: Uses document.fonts.load() when available (modern browsers)
  • Fallback Detection: Uses scroll-based text measurement technique for older browsers
  • Browser Bug Detection: Automatically detects and works around known bugs in WebKit and Safari
  • Lazy Measurement: Creates hidden test elements only when needed, with automatic cleanup

Capabilities

FontFaceObserver Constructor

Creates a new font observer instance for monitoring specific font family loading.

/**
 * Creates a font observer for the specified font family
 * @param {string} family - Font family name to monitor (required)
 * @param {Object} descriptors - Font descriptors (optional)
 * @param {string} descriptors.style - Font style, defaults to 'normal'
 * @param {string} descriptors.weight - Font weight, defaults to 'normal'  
 * @param {string} descriptors.stretch - Font stretch, defaults to 'normal'
 * @param {Window} context - Browser window context, defaults to current window (optional)
 */
new FontFaceObserver(family, descriptors, context);

Usage Examples:

// Basic font observer
const font = new FontFaceObserver('Arial');

// Font with descriptors
const boldItalicFont = new FontFaceObserver('Roboto', {
  weight: 'bold',
  style: 'italic'
});

// Font with all options
const condensedFont = new FontFaceObserver('Open Sans', {
  weight: '300',
  style: 'normal',
  stretch: 'condensed'
}, window);

Font Loading Detection

Monitors font loading and returns a Promise that resolves when the font becomes available.

/**
 * Monitors font loading and returns a Promise
 * @param {string} text - Custom test string for font detection, defaults to 'BESbswy'
 * @param {number} timeout - Timeout in milliseconds, defaults to 3000
 * @returns {Promise<FontFaceObserver>} Promise that resolves with the observer instance
 */
FontFaceObserver.prototype.load(text, timeout);

Usage Examples:

// Basic loading detection
font.load().then(() => console.log('Font loaded'));

// Custom test string for non-Latin fonts
const arabicFont = new FontFaceObserver('Arabic Font');
arabicFont.load('العربية').then(() => console.log('Arabic font loaded'));

// Custom timeout
font.load(null, 10000).then(() => console.log('Font loaded within 10 seconds'));

// Multiple fonts
const fontA = new FontFaceObserver('Font A');
const fontB = new FontFaceObserver('Font B');

Promise.all([fontA.load(), fontB.load()]).then(() => {
  console.log('Both fonts loaded');
});

Instance Properties

Properties available on FontFaceObserver instances.

// Font family name being monitored
fontObserver.family; // string

// Font style descriptor
fontObserver.style; // string

// Font weight descriptor  
fontObserver.weight; // string

// Font stretch descriptor
fontObserver.stretch; // string

// Browser window context
fontObserver.context; // Window

Error Handling

FontFaceObserver handles various error conditions:

font.load().then(
  function() {
    // Font loaded successfully
  },
  function(error) {
    // Font failed to load
    console.error('Font loading failed:', error.message);
    // Error message format: "3000ms timeout exceeded"
  }
);

Common error scenarios:

  • Timeout exceeded: Font didn't load within the specified timeout period
  • Network errors: Font file couldn't be fetched
  • Invalid font: Font family doesn't exist or has invalid descriptors

Browser Compatibility

FontFaceObserver works across all major browsers:

  • Chrome (desktop & Android)
  • Firefox
  • Opera
  • Safari (desktop & iOS)
  • Internet Explorer 8+
  • Android WebKit

The library automatically detects browser capabilities and uses the most efficient detection method available.

Types

For TypeScript users, here are the key type definitions:

interface FontDescriptors {
  style?: string;
  weight?: string;
  stretch?: string;
}

declare class FontFaceObserver {
  family: string;
  style: string;
  weight: string;
  stretch: string;
  context: Window;

  constructor(family: string, descriptors?: FontDescriptors, context?: Window);
  
  load(text?: string, timeout?: number): Promise<FontFaceObserver>;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/fontfaceobserver@2.3.x
Publish Source
CLI
Badge
tessl/npm-fontfaceobserver badge