fix: preserve inline styles and font preloads during ClientRouter head swap by veeceey · Pull Request #15514 · withastro/astro

veeceey · 2026-02-14T10:51:48Z

What

During client-side navigation with <ClientRouter />, the swapHeadElements() function removes all head elements that don't match one of two conditions: having data-astro-transition-persist, or being a <link rel="stylesheet"> with a matching href.

This means inline <style> tags -- including the @font-face declarations injected by the experimental <Font> component -- get removed from the DOM and re-appended on every navigation. The browser then re-evaluates the @font-face rules, which triggers font-display: swap and produces a visible font flash even though the font files are already cached.

Fix

Extended persistedHeadElement() to also preserve:

Inline <style> elements -- matched by comparing textContent. If the exact same style content exists in both the old and new head, the existing node is kept in place.
Font preload links (<link rel="preload" as="font">) -- matched by href, similar to how stylesheet links are already handled.

This is a small, targeted change to a single function. The existing behavior for all other head elements is unchanged.

Testing

Ran the existing view-transitions.test.js suite -- both tests pass.

@font-face

…d swap During client-side navigation with ClientRouter, swapHeadElements() only preserved elements with data-astro-transition-persist and stylesheet links. Inline <style> tags (including @font-face declarations from <Font>) were removed and re-appended on every navigation, forcing the browser to re-evaluate them and triggering a visible font flash (FOUT). This extends persistedHeadElement() to also match: - Inline <style> elements by their text content - Font preload links (link[rel=preload][as=font]) by href When an identical element exists in both the old and new document head, it stays in the DOM instead of being removed and re-inserted. Fixes withastro#15465

changeset-bot · 2026-02-14T10:51:54Z

🦋 Changeset detected

Latest commit: 5767c7b

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

codspeed-hq · 2026-02-15T10:39:33Z

Merging this PR will not alter performance

✅ 9 untouched benchmarks

_{Comparing veeceey:fix/issue-15465-font-head-swap (5767c7b) with main (b30a2c4)}

Copilot

Pull request overview

This PR fixes font flashing (FOUT) during client-side navigation with <ClientRouter /> by preserving inline <style> elements and font preload links during head element swaps. Previously, inline styles containing @font-face declarations from the experimental <Font> component were removed and re-inserted on every navigation, causing the browser to re-evaluate them and trigger visible font flashes.

Changes:

Extended the persistedHeadElement() function to preserve inline <style> elements by matching their textContent
Added preservation logic for <link rel="preload" as="font"> elements by matching their href attribute
Added appropriate changeset documenting the fix

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
packages/astro/src/transitions/swap-functions.ts	Extended `persistedHeadElement()` to preserve inline styles and font preload links during head swaps
.changeset/fix-font-head-swap.md	Documented the patch-level change fixing font flash during ClientRouter navigation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

martrapp

Thank you for opening this PR. The change looks good to me.

I was wondering whether we should also match the attributes of the style element, alongside the content? I did not find an example with practical relevance.

It would be great if you could add a new e2e test to show that identical elements survive the swap untouched, but it is not a problem if you decide to leave it out.

veeceey · 2026-02-16T00:11:35Z

Thanks for the review! Good point about matching style element attributes too — I had the same thought but couldn't come up with a case where it would matter in practice either, since the inline styles generated by Font only differ in content. Happy to add that if a real use case comes up down the line.

As for the e2e test, I'll look into adding one that verifies the style and preload elements persist through a navigation swap. Will update the PR if I get something solid together.

@font-face

Add a test that verifies inline <style> elements (e.g. @font-face declarations) and font preload links survive head swaps during client-side navigation, preventing FOUT (Flash of Unstyled Text). The test navigates between two pages sharing identical inline styles and font preloads, and asserts that the original DOM nodes persist rather than being removed and re-inserted. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

veeceey · 2026-02-20T06:04:19Z

Added the e2e test as requested!

Remove unused variables (styleIdBefore, preloadIdBefore) to fix biome lint errors. Replace fragile exact style count comparison with greaterThan(0) checks, since Astro may inject additional style elements during client-side navigation. Use data-attribute selectors to directly query the marked DOM nodes instead of relying on querySelector order. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

martrapp · 2026-02-20T09:54:19Z

Great! Thank you very much for adding the test!
I will take a look and will probably make the test a bit more concise.

veeceey · 2026-02-20T10:25:45Z

Sure thanks !!

…

________________________________ From: Martin Trapp ***@***.***> Sent: Friday, February 20, 2026 1:54:40 AM To: withastro/astro ***@***.***> Cc: Varun Chawla ***@***.***>; Author ***@***.***> Subject: Re: [withastro/astro] fix: preserve inline styles and font preloads during ClientRouter head swap (PR #15514) [https://avatars.githubusercontent.com/u/94928215?s=20&v=4]martrapp left a comment (withastro/astro#15514)<#15514 (comment)> Great! Thank you very much for adding the test! I will take a look and will probably make the test a bit more concise. — Reply to this email directly, view it on GitHub<#15514 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AIE72BACI5CH7IF4EETI73D4M3KWBAVCNFSM6AAAAACVD5AHQSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSMZSG43DAOJXHA>. You are receiving this because you authored the thread.Message ID: ***@***.***>

martrapp

LGTM!

veeceey added 2 commits February 14, 2026 02:51

add changeset

46dc9af

github-actions Bot added the pkg: astro Related to the core `astro` package (scope) label Feb 14, 2026

Merge branch 'main' into fix/issue-15465-font-head-swap

e7d4eee

martrapp requested a review from Copilot February 15, 2026 11:46

Copilot started reviewing on behalf of martrapp February 15, 2026 11:46 View session

Copilot AI reviewed Feb 15, 2026

View reviewed changes

martrapp reviewed Feb 15, 2026

View reviewed changes

veeceey and others added 2 commits February 18, 2026 21:25

Merge branch 'main' into fix/issue-15465-font-head-swap

25f9dc9

martrapp added 3 commits February 20, 2026 16:04

Make the test a bit more concise

345751f

Merge branch 'main' into fix/issue-15465-font-head-swap

a0f5ca9

Update fix-font-head-swap.md

aca1c59

martrapp approved these changes Feb 20, 2026

View reviewed changes

Merge branch 'main' into fix/issue-15465-font-head-swap

5767c7b

martrapp merged commit 999a7dd into withastro:main Feb 22, 2026
26 checks passed

astrobot-houston mentioned this pull request Feb 22, 2026

[ci] release (beta) #15590

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: preserve inline styles and font preloads during ClientRouter head swap#15514

fix: preserve inline styles and font preloads during ClientRouter head swap#15514
martrapp merged 10 commits into
withastro:mainfrom
veeceey:fix/issue-15465-font-head-swap

veeceey commented Feb 14, 2026

Uh oh!

changeset-bot Bot commented Feb 14, 2026 •

edited

Loading

Uh oh!

codspeed-hq Bot commented Feb 15, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

martrapp left a comment

Uh oh!

veeceey commented Feb 16, 2026

Uh oh!

veeceey commented Feb 20, 2026

Uh oh!

martrapp commented Feb 20, 2026

Uh oh!

veeceey commented Feb 20, 2026 via email

Uh oh!

martrapp left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

veeceey commented Feb 14, 2026

What

Fix

Testing

Uh oh!

changeset-bot Bot commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

codspeed-hq Bot commented Feb 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

martrapp left a comment

Choose a reason for hiding this comment

Uh oh!

veeceey commented Feb 16, 2026

Uh oh!

veeceey commented Feb 20, 2026

Uh oh!

martrapp commented Feb 20, 2026

Uh oh!

veeceey commented Feb 20, 2026 via email

Uh oh!

martrapp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

changeset-bot Bot commented Feb 14, 2026 •

edited

Loading

codspeed-hq Bot commented Feb 15, 2026 •

edited

Loading