Why does my custom font cause layout shift on Spotlight?

Almost always one of three causes: `font-display` defaults to `auto` which blocks rendering and then swaps, the WOFF2 isn't preloaded so the browser fetches it after parsing CSS, or a Liquid block is toggling a class via JavaScript after first paint. Spotlight's system fallback has different metrics than most custom faces, which exaggerates the shift if any of those three are in play.

How do I preload a font on Spotlight to fix CLS?

Open Spotlight's `layout/theme.liquid` and insert ` ` inside the ` ` block, above the main stylesheet link. Preloading tells the browser to fetch the font in parallel with the HTML, eliminating the wait that otherwise happens between CSS parse and font request.

Should I use font-display: swap or font-display: optional on Spotlight?

`swap` for nearly all Spotlight stores. `optional` is theoretically zero-CLS because it skips the swap if the font isn't ready in 100ms — but on a fashion & entertainment site, brand consistency matters, and `swap` plus a preload is functionally CLS-free without sacrificing the custom face. The generator above defaults to `swap`.

What size budget should I aim for to keep CLS at zero on Spotlight?

Aim for sub-50KB WOFF2 per face. Spotlight's critical render path expects the font to arrive before the layout settles — at 50KB on 4G that's well within the LCP window. If your face is larger (heavy display or icon-loaded), subset it to Latin-only and only include the weights your store actually uses, which often cuts file size by 60-70%.

Shopify Spotlight · Free, no signup · Last updated July 8, 2026

Fix Custom Font Layout Shift on Shopify Spotlight

Layout shift on Spotlight after a custom font installs is almost always a missing `font-display: swap`, an unpreloaded WOFF2, or a JS-driven font swap that fires after first paint — fix all three and your CLS drops to zero.

Spotlight ships clean Core Web Vitals out of the box, but a poorly configured custom font can knock CLS up by 0.10 or more. Because a video- and motion-forward free theme for fashion, audio, and entertainment brands., the merchant audience tends to research these issues directly on mobile — making CLS a conversion-impacting metric, not just an SEO one.

Fashion and entertainment stores can push cinematic display sizing for headings to match hero video, but keep the body face simple so the drama stays in the imagery, not the paragraph text.

Custom font nameBecomes the @font-face font-family

Faces(1 face)

Face 1·Regular 400

WeightStyle

Formats

Filename (no extension)Leave blank to auto-generate from the font name. Set it to your exact uploaded filename if your font shipped as e.g. Calibre-Bold.woff2 — then paste Calibre-Bold here.

Each face becomes its own @font-face block. The filename field on each row defaults to a clean pattern, but you can paste the exact filename you uploaded if your foundry shipped it with a different name — no renaming required.

Apply to

Controls which Dawn typography roots the CSS variable block overrides.

Live preview

Add to cart · Free shipping · 30-day returns

Drop a WOFF2 / WOFF / TTF file here to preview your actual font. The file stays in your browser — nothing is uploaded.

Paste these three blocks in order. They're independent files in your theme — copying one without the others won't break the store.

Step 1: @font-face CSS

Upload your font files to the theme's assets/ folder, then paste this at the bottom of assets/base.css. Shopify's asset_url filter resolves the file paths at render time.

@font-face {
  font-family: "My Brand Sans";
  src: url({{ 'my-brand-sans.woff2' | asset_url }}) format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

Step 1: @font-face CSS

Upload your font files to the theme's assets/ folder, then paste this at the bottom of assets/base.css. Shopify's asset_url filter resolves the file paths at render time.

@font-face {
  font-family: "My Brand Sans";
  src: url({{ 'my-brand-sans.woff2' | asset_url }}) format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

Step 2: settings_schema.json

Adds a Theme Editor section so non-technical merchants can toggle the font on or off.

{
  "name": "My Brand Sans (primary custom font)",
  "settings": [
    {
      "type": "header",
      "content": "My Brand Sans typography"
    },
    {
      "type": "paragraph",
      "content": "Upload your font file (woff2) to your theme's Assets folder. The @font-face block will resolve them via {{ 'my-brand-sans.woff2' | asset_url }}."
    },
    {
      "type": "font_picker",
      "id": "my_brand_sans_heading_font",
      "label": "Native Theme Editor heading fallback (only used if you don't upload custom files)"
    },
    {
      "type": "font_picker",
      "id": "my_brand_sans_body_font",
      "label": "Native Theme Editor body fallback (only used if you don't upload custom files)"
    },
    {
      "type": "checkbox",
      "id": "my_brand_sans_use_for_both",
      "label": "Use this font for both headings and body",
      "default": true
    },
    {
      "type": "select",
      "id": "my_brand_sans_apply_to",
      "label": "Apply My Brand Sans (only used when \"Use this font for both\" is unchecked)",
      "options": [
        {
          "value": "headings",
          "label": "Headings only"
        },
        {
          "value": "body",
          "label": "Body only"
        },
        {
          "value": "both",
          "label": "Headings and body"
        },
        {
          "value": "off",
          "label": "Disabled"
        }
      ],
      "default": "both"
    },
    {
      "type": "paragraph",
      "content": "font-display strategy: swap — controls how text renders while the font file is downloading. \"swap\" is the recommended default."
    },
    {
      "type": "checkbox",
      "id": "my_brand_sans_load_woff_fallback",
      "label": "Also load WOFF fallback (legacy browsers)",
      "default": false
    }
  ]
}

Step 3: CSS variable overrides

Retargets the theme's --font-heading-family / --font-body-family. Survives theme updates.

:root,
[data-shopify-section],
.shopify-section {
  --font-heading-family: "My Brand Sans", sans-serif;
  --font-heading-style: normal;
  --font-heading-weight: 400;
  --font-body-family: "My Brand Sans", sans-serif;
  --font-body-style: normal;
  --font-body-weight: 400;
}

How to use this on Spotlight

Three fixes cover almost every case.
First, set `font-display: swap` on every @font-face declaration so the browser renders fallback metrics immediately and swaps in your custom face when ready.
Second, preload the WOFF2 with `<link rel="preload" as="font" type="font/woff2" crossorigin>` from Spotlight's `theme.liquid` head — preloading saves the round-trip the browser would otherwise make after parsing CSS.
Third, override `--font-heading-family` instead of swapping classes via JavaScript: Spotlight's heading selectors read the variable at first paint, eliminating the post-load reflow that JS-driven swaps cause.
Verify with the Performance panel in DevTools — the CLS bar should be flat across the load.

Typography Kit

Skip straight to a finished result

Every step above, already done for you on Spotlight — a proven font pairing, the install code pre-built, the licensing confirmed, and a specimen so you see it before you ship it. One-time, instant download, no account.

See the Typography Kits$19 · one-time · instant download

Frequently asked questions

Why does my custom font cause layout shift on Spotlight?
Almost always one of three causes: `font-display` defaults to `auto` which blocks rendering and then swaps, the WOFF2 isn't preloaded so the browser fetches it after parsing CSS, or a Liquid block is toggling a class via JavaScript after first paint. Spotlight's system fallback has different metrics than most custom faces, which exaggerates the shift if any of those three are in play.
How do I preload a font on Spotlight to fix CLS?
Open Spotlight's `layout/theme.liquid` and insert `<link rel="preload" href="{{ 'yourfont.woff2' | asset_url }}" as="font" type="font/woff2" crossorigin>` inside the `<head>` block, above the main stylesheet link. Preloading tells the browser to fetch the font in parallel with the HTML, eliminating the wait that otherwise happens between CSS parse and font request.
Should I use font-display: swap or font-display: optional on Spotlight?
`swap` for nearly all Spotlight stores. `optional` is theoretically zero-CLS because it skips the swap if the font isn't ready in 100ms — but on a fashion & entertainment site, brand consistency matters, and `swap` plus a preload is functionally CLS-free without sacrificing the custom face. The generator above defaults to `swap`.
What size budget should I aim for to keep CLS at zero on Spotlight?
Aim for sub-50KB WOFF2 per face. Spotlight's critical render path expects the font to arrive before the layout settles — at 50KB on 4G that's well within the LCP window. If your face is larger (heavy display or icon-loaded), subset it to Latin-only and only include the weights your store actually uses, which often cuts file size by 60-70%.

Still choosing a font?

Browse the best free fonts for Shopify with performance and licensing notes, the Shopify font pairings that work, or run the 30-second typography audit to get a recommendation for your store.