Solving CLS Problem Caused by Font Fallback When Using Material Symbols with CSS Font Loading

Türkçe versiyon

Impact of Asynchronous Font Loading on CLS

Icon libraries like Material Symbols work by replacing the text content (text node) of elements like <span> or <i> with glyphs via a font-family. The core problem is that these icon font files (generally in WOFF2 format) are fetched asynchronously. This can lead to an unpredictable Cumulative Layout Shift (CLS) in the browser’s render pipeline.

The rendering process follows these steps:

1. DOM Parsing: The browser parses an element containing a text node, such as <span>settings</span>.
2. Render Tree Construction: The font-family: ‘Material Symbols Outlined’ rule from the CSSOM is applied to this element. However, at this stage, the font file has not yet been downloaded from the network.
3. Layout (Reflow): The browser calculates the geometry (bounding box) of each element in the render tree. Since the icon font is not yet available, this calculation is performed based on the system’s default fallback font and the dimensions of the “settings” text.
4. Font Loading and Swap: When the asynchronously loaded icon font becomes available, the browser performs a “font swap” operation. The “settings” text is replaced by the icon glyph, which often has entirely different width and height metrics than the text.
5. Re-Layout: This size change forces the browser to perform a new layout (reflow) calculation. This second layout directly contributes negatively to the CLS score by shifting the position of the element and its affected surrounding elements.

The problem lies in the lack of synchronization between the moment an element is included in the layout and the moment a critical resource (font) required for rendering becomes ready.

Synchronizing the Render Flow

To eliminate CLS, it is necessary to defer the inclusion of the icon element into the render tree until its dependent font resource is fully loaded. This ensures that the element enters the layout calculation only once, with its final and stable dimensions.

This strategy consists of two main components:

1. Conditional Rendering with CSS: Initially, the element is completely removed from the layout flow using display: none;. Alternatives like visibility: hidden; or opacity: 0; are insufficient because they keep the element in the layout and reserve its space, which would still cause CLS when the font swap occurs.
2. Font Status Detection with JavaScript: The CSS Font Loading API (document.fonts) is used to programmatically track the loading status of the target font, and this status is used to trigger a state change for rendering.

Technical Implementation

CSS Layer: Excluding from Layout

CSS is structured to manage two states via a “sentinel” class (.fonts-loaded): the initial (default) state and the state after the font is loaded.

/*
 * Initial State:
 * The element is completely outside the layout flow and render tree with 'display: none'.
 * This guarantees zero CLS until the font is loaded.
 * Transition is set to work only on opacity.
 */.material-symbols-outlined {
  display: none;
  opacity: 0;
  transition: opacity 0.3s ease;
}

/*
 * Final State (when .fonts-loaded is active):
 * The element is included in the layout with 'display: inline-block'.
 * At this stage, the font is already loaded, so its dimensions are stable and will not cause reflow.
 * Opacity is set to 1 to make the element visible.
 */.fonts-loaded .material-symbols-outlined {
  display: inline-block;
  opacity: 1;
}

/*
 * Initial State:
 * The element is completely outside the layout flow and render tree with 'display: none'.
 * This guarantees zero CLS until the font is loaded.
 * Transition is set to work only on opacity.
 */
.material-symbols-outlined {
  display: none;
  opacity: 0;
  transition: opacity 0.3s ease;
}

/*
 * Final State (when .fonts-loaded is active):
 * The element is included in the layout with 'display: inline-block'.
 * At this stage, the font is already loaded, so its dimensions are stable and will not cause reflow.
 * Opacity is set to 1 to make the element visible.
 */
.fonts-loaded .material-symbols-outlined {
  display: inline-block;
  opacity: 1;
}

JavaScript Layer: CSS Font Loading API Integration

The following async IIFE (Immediately Invoked Function Expression) runs as soon as the page loads, monitoring the font status.

<script>
  (async () => {
    // The 'document.fonts.load()' method returns a Promise that resolves
    // when the specified font has finished loading.
    // The first argument to the method is a string specifying the font's style and family ('[style] [weight] [size] [family]').
    // Specifying a size ('1em') is a requirement of the API.
    try {
      await document.fonts.load('1em "Material Symbols Outlined"');

      // When the Promise resolves successfully, the font is guaranteed to be available.
      // At this point, the sentinel class is added to the root element of the DOM
      // (.documentElement, i.e., <html>). This efficiently triggers the CSS rules.
      document.documentElement.classList.add('fonts-loaded');
    } catch (error) {
      // Error handling in case the font cannot be loaded (e.g., network error).
      console.error('Material Symbols font could not be loaded, CLS mitigation failed.', error);
    }
  })();
</script>

<script>
  (async () => {
    // The 'document.fonts.load()' method returns a Promise that resolves
    // when the specified font has finished loading.
    // The first argument to the method is a string specifying the font's style and family ('[style] [weight] [size] [family]').
    // Specifying a size ('1em') is a requirement of the API.
    try {
      await document.fonts.load('1em "Material Symbols Outlined"');

      // When the Promise resolves successfully, the font is guaranteed to be available.
      // At this point, the sentinel class is added to the root element of the DOM
      // (.documentElement, i.e., <html>). This efficiently triggers the CSS rules.
      document.documentElement.classList.add('fonts-loaded');
    } catch (error) {
      // Error handling in case the font cannot be loaded (e.g., network error).
      console.error('Material Symbols font could not be loaded, CLS mitigation failed.', error);
    }
  })();
</script>

This integration provides a robust solution to the CLS problem caused by Material Symbols icons. The inclusion of the icon element in the layout is programmatically linked to the availability of the critical rendering resource, the font file. Since the element is included in the render flow only when its final and immutable geometry is known, re-layout and layout shift caused by font fallback and subsequent swap are completely eliminated.

This method is the ideal approach for managing rendering issues caused by asynchronous resource dependencies in performance-oriented applications that are sensitive to Core Web Vitals metrics.