What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
If a Chromatic snapshot or interaction test captures a story before its custom font is ready, the browser may render text in a fallback font first. Different text dimensions can shift elements and create visual diffs or inconsistent results. Start by checking the failed font URL, then preload the exact font in Storybook; serve it locally or explicitly wait for it when needed.
Why late fonts make Chromatic tests fail
Browsers may fetch a custom font only when page content first needs it. Until the font arrives, text can use a fallback face; when the custom font loads, the browser lays out the text again. Changes in glyph widths, line breaks, and element dimensions can alter positions that a snapshot or interaction test observes.
As an Amazon Associate I earn from qualifying purchases.
Chromatic says it waits for resources such as fonts before capturing a snapshot, but external resources can still fail or arrive late, and asynchronous rendering can make later resources difficult to detect reliably. Its resource-loading documentation describes 15 seconds to render a story and an additional 15 seconds for interaction tests; those are documented timing limits, not a guarantee that a slow or unreachable font will be ready. Chromatic may retry when resources do not arrive in time. See Chromatic’s resource-loading guidance and unstable-test debugging.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →As Chromatic puts it, “Chromatic waits for resources like images and fonts to load before capturing a snapshot.” The practical distinction is that a wait cannot make an unavailable or persistently slow external font dependable.
#1 Best Overall
Diagnose the specific font request first
- Open the failed build’s resource warning or unstable-test trace and identify the font URL.
- Run Storybook and verify that the URL is valid and the font file actually loads in the browser.
- Check whether the test browser can reach the host. External CDN access, network restrictions, or firewall rules can make a font available locally but unavailable to the test.
- Confirm that the font URL in the preload matches the face and file your CSS requests, including the correct weight and style variant.
Chromatic’s resource-loading documentation explains how resource warnings can help locate the problem.
Preload the font in Storybook
Chromatic’s preferred fix is to preload the precise font file from Storybook’s .storybook/preview-head.html. Use the actual file URL, font format, and cross-origin setting appropriate to your asset:
<link
rel="preload"
href="/fonts/your-font.woff2"
as="font"
type="font/woff2"
crossorigin="anonymous"
>Replace /fonts/your-font.woff2 with the URL used by your stylesheet. A preload for the wrong weight, file, or URL will not ensure that the requested face is ready. For details and Chromatic’s Storybook configuration guidance, see Font loading in Chromatic and the Chromatic for Storybook quickstart.
Rank #2
Make font delivery deterministic
If the font comes from an external host, consider placing the test font files in Storybook’s static directory and pointing the test stylesheet at those local assets. This avoids depending on an external network request during capture while preserving the intended typeface. Production can keep its separate delivery arrangement if that better fits deployment needs.
Local hosting does not remove the need to use the correct font URL or ensure the asset is included in the Storybook build. Verify the request in the browser and in Chromatic’s failure details.
Wait explicitly when a story needs a font
For a story that must not proceed until a face is ready, Storybook’s global loader can use the browser Font Loading API. Load a specific face when you know which one the story needs:
export const loadFonts = async () => {
await document.fonts.load('400 1em Font Name');
};
export const globalTypes = {};
export const loaders = [loadFonts];Adapt this to the Storybook version and configuration already used by your project; the important part is awaiting the font request before the story is captured. Chromatic’s font-loading documentation shows how to gate its loader for Chromatic with isChromatic().
Alternatively, await document.fonts.ready to wait until fonts used by the document have loaded and layout operations are complete:
await document.fonts.ready;This promise does not load every face merely declared in CSS: it resolves after fonts used by the page have completed loading and associated layout work. For the browser API’s exact behavior, consult MDN’s documentation on FontFaceSet.ready, Document.fonts, and the CSS Font Loading API.
Prevent interaction tests from starting too early
Chromatic interaction tests run as soon as the DOM loads. A play function can therefore begin while an external font is still in flight, depending on network timing. Preloading in the document head is preferable because it starts the request early. If you cannot preload, await the required font before the interaction depends on text dimensions. A fixed delay is a weaker fallback: it may be unnecessarily slow on a fast run and still too short on a slow one. See Chromatic’s interaction-test guidance.
Choose a fallback or disable custom fonts only deliberately
Keep a suitable CSS fallback
A fallback font helps keep text legible if the custom face is unavailable. It may not have matching metrics, so it is resilience rather than a synchronization fix. Chromatic lists Arial, Verdana, and Trebuchet MS as sans-serif examples; Georgia and Times New Roman for serif; and Courier New or Courier for monospace. Choose a stack that covers the languages your UI displays. See Chromatic’s font-loading guidance.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsUse font-display: optional only if fallback rendering is acceptable
Chromatic documents font-display: optional as an option for its environment. It can avoid waiting for a custom face, but the snapshot may then show the fallback appearance. Use it only when that is acceptable for the visual test, not as a way to verify the custom typography.
Best Value
Pick the remedy that fits the failure
| Remedy | Reliability and fidelity | Trade-off |
|---|---|---|
| Local static font plus preload | Reduces external network dependence while retaining the intended typeface. | Requires maintaining the local asset and matching preload URL to the requested face. |
| Font Loading API wait | Explicitly synchronizes a story with the needed face or used page fonts. | The relevant face must be requested; waiting for document.fonts.ready does not load unused declarations. |
| Web-safe fallback | Provides a resilient alternative if the custom font cannot load. | Different font metrics can still change layout and visual results. |
font-display: optional |
Can avoid dependency on the custom font in Chromatic. | May render the fallback instead of the intended typography. |
| Fixed delay | May give an external request extra time in a particular run. | Timing-dependent; not a dependable substitute for preload or explicit readiness. |
Troubleshoot common symptoms
- The font request is 404 or absent: Correct the asset path and ensure the font is included in Storybook’s static output.
- The request works locally but fails in Chromatic: Check test-browser access to the external host and network restrictions; consider serving the test asset locally.
- The preload appears to have no effect: Verify that its URL, format, weight, and style correspond to the face requested in CSS.
- The snapshot still has shifted text: Ensure the story actually requests the face, and wait for that face before capture or interaction rather than relying on an unused font declaration.
- Only interaction tests are unstable: The interaction may start before an external font arrives. Start the font request earlier with preload and synchronize before text-dependent actions.
- A delay fixes some runs but not others: Replace the timing guess with local delivery, preload, or an explicit Font Loading API wait.
- Fallback rendering is consistent but visually wrong: Remove the optional-font workaround if typography is under test, and make the intended font available before capture.
Or skip the browser setup
If your goal is a website screenshot rather than a Chromatic component test, ScreenshotNeo can return a screenshot or PDF from one GET request. For example, this cURL request captures a page as WebP:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before capture, with each cleanup step configurable. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free.
Frequently Asked Questions
Does waiting for document.fonts.ready load every font declared in CSS?
No. It resolves after fonts used by the document have loaded and layout operations have completed; unused declared faces need not load.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Should I use a longer fixed delay to fix late-font failures?
A delay depends on network timing and can remain too short on a slow run. Preload the needed font or explicitly await it instead.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
