How to Use Custom Web Fonts in PixiJS

Using custom web fonts loaded via CSS in Pixi.js can often result in rendering issues, such as text falling back to default system fonts or failing to display. This article explains why these rendering glitches occur and provides practical, step-by-step solutions to ensure your CSS web fonts are fully loaded and ready before PixiJS attempts to render them.

Why Custom Fonts Fail to Render in PixiJS

PixiJS renders text by drawing characters onto a hidden HTML5 <canvas> element and using that canvas as a texture. Because canvas rendering is instantaneous, PixiJS requires the font to be fully loaded and active in the browser’s memory the exact moment the PIXI.Text object is created.

If you define a font in CSS and immediately try to use it in PixiJS, the browser will often render the text using a fallback system font (like Arial) because the custom font file is still downloading in the background. Once the font finally finishes downloading, PixiJS does not automatically re-render the text, leaving you with incorrect typography.

To fix this, you must force PixiJS to wait until the fonts are completely loaded.

The modern and native way to handle this is the browser’s built-in CSS Font Loading API. This API allows you to programmatically detect when a specific font has loaded before initializing your PixiJS application or rendering text.

Step 1: Define your font in CSS

First, define your custom font using @font-face in your CSS file:

@font-face {
    font-family: 'MyCustomFont';
    src: url('fonts/MyCustomFont.woff2') format('woff2');
}

Step 2: Load the font in JavaScript

Before creating your PixiJS text, use document.fonts.load to ensure the font is ready:

// Wait for the specific font to load
document.fonts.load('12px "MyCustomFont"').then(() => {
    // Initialize PixiJS Text once loaded
    const style = new PIXI.TextStyle({
        fontFamily: 'MyCustomFont',
        fontSize: 36,
        fill: '#ffffff'
    });

    const richText = new PIXI.Text('Hello PixiJS!', style);
    app.stage.addChild(richText);
});

Alternatively, if you want to wait for all fonts defined in your CSS to load, you can use:

document.fonts.ready.then(() => {
    // Initialize your PixiJS application here
});

Solution 2: Preload Fonts with HTML and CSS

If you prefer not to use JavaScript promises, you can force the browser to preload the font using HTML <link> tags. This tells the browser to download the font file immediately during the initial page load.

Add this tag inside the <head> of your HTML document:

<link rel="preload" href="fonts/MyCustomFont.woff2" as="font" type="font/woff2" crossorigin>

Step 2: Use a hidden element

Sometimes, browsers will preload a font but won’t actually activate it until it is used in the DOM. You can force activation by creating a temporary, hidden HTML element in your HTML:

<div style="font-family: 'MyCustomFont'; position: absolute; visibility: hidden; height: 0; width: 0;">
    Force Load
</div>

Once the DOM is ready, the font will be active in memory, allowing PixiJS to access and render it immediately.

Solution 3: Use the WebFont Loader Library

If you need to support older browsers or are loading fonts from third-party services like Google Fonts, the WebFont Loader library (co-developed by Google and Typekit) is a highly reliable solution.

Step 1: Include the library

Include the library via CDN in your HTML:

<script src="https://ajax.googleapis.com/ajax/libs/webfont/1.6.26/webfont.js"></script>

Step 2: Configure and load your fonts

Initialize WebFont Loader and start your PixiJS setup inside the active callback:

WebFont.load({
    custom: {
        families: ['MyCustomFont']
    },
    active: () => {
        // This triggers only when the fonts are fully loaded and active
        const text = new PIXI.Text('Loaded via WebFont Loader', {
            fontFamily: 'MyCustomFont',
            fontSize: 24,
            fill: 0xffffff
        });
        app.stage.addChild(text);
    }
});