Skip to content

InlineFontLoader — Local Inline Font Loader

Extension for Magento 2

User Guide

CopeX GmbH
Web: https://copex.io
Email: office@copex.io

Table of Contents

Section Page
1 Requirements 2
2 Installation 2
3 Configuration 2
4 How It Works 5
5 Troubleshooting 6

1 Requirements

  • Magento 2.4 or higher
  • PHP 8.1 or higher
  • Locally stored font files in the theme or in a module

2 Installation

Via Composer

composer require copex/module-inlinefontloader
php bin/magento module:enable CopeX_InlineFontLoader
php bin/magento setup:upgrade
php bin/magento cache:flush

3 Configuration

The module configuration is located in the Magento 2 admin panel under Stores > Configuration > General > Web > Local Inline Font Loader.

Configuration

3.1 Activation

  • Enable — Enables or disables the module. When disabled, no @font-face declarations or preload links are injected into the HTML header.

3.2 Font Types

  • Font Types — A multi-select that determines which font file formats are included in the @font-face CSS declarations. Only the selected formats are included in the generated CSS.

The following formats are available:

Format File Extension CSS Format
WOFF2 .woff2 woff2
WOFF .woff woff
TrueType .ttf truetype
EOT (Internet Explorer) .eot embedded-opentype
SVG .svg svg

Recommendation: WOFF2 alone is sufficient for modern browsers. For maximum compatibility, WOFF2 and WOFF can be combined.

3.3 Preload Font Types

  • Preload Font Types — Determines which font file formats get <link rel="preload"> tags injected into the HTML header. Preloading speeds up font loading because the browser requests them earlier.

Note: For preloading, usually only WOFF2 should be selected, as it's the primary format for modern browsers.

3.4 Font Definitions

  • Configure — A table of font definitions to load.

Table structure:

Column Description
Definition CSS properties of the @font-face declaration
Path to font Path to the font file without file extension
Preload Whether a preload link should be generated for this font definition

Definition (example):

font-family:'Roboto';font-style: normal;font-display: swap;font-weight: 400;

Path to font (examples):

  • Theme-relative path: fonts/roboto/roboto-v30-latin-regular
  • Module path: CopeX_Core::fonts/myfont

The module automatically appends file extensions based on the configured font types.

Complete configuration example:

Definition Path to font Preload
font-family:'Roboto';font-style:normal;font-display:swap;font-weight:400; fonts/roboto/roboto-v30-latin-regular Yes
font-family:'Roboto';font-style:italic;font-display:swap;font-weight:400; fonts/roboto/roboto-v30-latin-italic No
font-family:'Roboto';font-style:normal;font-display:swap;font-weight:700; fonts/roboto/roboto-v30-latin-700 No

4 How It Works

4.1 Generated HTML

The module injects the following code into the <head> section of storefront pages:

Preload links (for fonts marked as "Preload"): 

<link rel="preload" href="...fonts/roboto-v30-latin-regular.woff2" as="font" type="font/woff2" crossorigin>

Inline CSS with @font-face: 

<style>
@font-face {
  font-family: 'Roboto';
  font-style: normal;
  font-display: swap;
  font-weight: 400;
  src: local('Roboto'),
       url('.../fonts/roboto-v30-latin-regular.woff2') format('woff2'),
       url('.../fonts/roboto-v30-latin-regular.woff') format('woff');
}
</style>

4.2 Fallback Strategy

From version 1.0.4, the module prefers remote fonts and uses local fonts only as a fallback. When a path to a font name is detected (e.g. Roboto), the module automatically adds local('Roboto') as the first source in the src list.

4.3 Caching

The generated @font-face declarations are stored in the Magento cache with the config tag. After changes to the configuration, the cache must be flushed for the new settings to take effect.

Flush cache: 

php bin/magento cache:flush

4.4 Asset Validation

On load, the module checks whether the configured font files actually exist. Missing files are tolerated and do not cause errors — the corresponding src entries are simply skipped.

5 Troubleshooting

  • Fonts are not loading — Make sure the module is enabled and the font file paths are correctly configured. Check in the browser developer tools (Network tab) whether the font files are being requested correctly.

  • @font-face is not generated — Flush the Magento cache after configuration changes. The generated declarations are cached and are not automatically updated after a configuration change.

  • Font does not appear in the browser — Check that the path to the font file is correct and that the file exists in the configured format. Theme-relative paths must be placed under web/ in the theme directory.

  • 404 errors for font files — Make sure static files have been deployed (php bin/magento setup:static-content:deploy). Verify that the specified path relative to the theme's web/ directory is correct.

  • Preload links are missing — Check that the desired formats are selected under Preload Font Types. Also, the corresponding font definition in the configuration table must have Preload: Yes set.

License

Proprietary — CopeX GmbH. One license per production Magento instance.