Add Soft Navigation docs by tunetheweb · Pull Request #45053 · mdn/content

tunetheweb · 2026-08-07T18:45:48Z

Description

Chrome 151 includes the Soft Navigations and Interaction Contentful Paint spec addressing a long-standing issue of measuring performance across SPAs

Motivation

Document APIs available unflagged in Chromium-based browsers

Additional details

Related issues and pull requests

I've a BCD change in flight for this too (mdn/browser-compat-data#30195), but it's waiting on w3c/browser-specs#2593 to land first

github-actions · 2026-08-07T18:47:36Z

Preview URLs (21 pages)

Flaws (1)

Note! 20 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Glossary/Contentful_paint
Title: Contentful paint
Flaw count: 1

macros:
- Macro htmlelement produces link /en-US/docs/Web/HTML/Reference/Elements/svg which doesn't resolve

External URLs (9)

URL: /en-US/docs/Glossary/Contentful_paint
Title: Contentful paint

https://github.com/WICG/container-timing (1 time) (Note! This may be a new URL 👀)
https://w3c.github.io/paint-timing/ (2 times) (Note! This may be a new URL 👀)

URL: /en-US/docs/Glossary/First_contentful_paint
Title: First Contentful Paint (FCP)

https://web.dev/articles/fcp (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Glossary/Soft_navigation
Title: Soft navigation

https://angular.dev/ (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/Single-page_application (1 time) (Note! This may be a new URL 👀)
https://react.dev/ (1 time) (Note! This may be a new URL 👀)
https://vuejs.org/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/InteractionContentfulPaint
Title: InteractionContentfulPaint

https://developer.chrome.com/docs/web-platform/soft-navigations (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/PerformanceSoftNavigation
Title: PerformanceSoftNavigation

https://developer.chrome.com/docs/web-platform/soft-navigations (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-08-12 11:20:50)

tunetheweb · 2026-08-07T18:49:05Z

@mmocny could you review for technical accuracy?

tunetheweb · 2026-08-07T18:59:21Z

@chrisdavidmills as discussed

chrisdavidmills

Very nice work, @tunetheweb, this generally makes sense. I've left quite a few comments, but most of them are fairly minor language nitpicks.

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

…ndex.md

tunetheweb · 2026-08-10T11:37:40Z

Thanks very much @chrisdavidmills for the detailed review and spotting those errors!

I think I've addressed all the feedback. I've left a couple of comments open in case you wanna discuss those further.

Ready for another look.

mmocny

Lots of good new content!

I spotted a few small grammar issues, but I wonder if AI reviewer would spot more. I didn't try.

chrisdavidmills

Nice work, @tunetheweb, this is pretty close now. I've left a few more comments on the new content you added last time around.

chrisdavidmills · 2026-08-11T14:20:16Z

+
+The **`getLargestInteractionContentfulPaint()`** method of the {{domxref("PerformanceSoftNavigation")}} interface returns the current largest {{domxref("InteractionContentfulPaint")}} relevant to this soft navigation.
+
+Some {{Glossary("SPA", "Single Page Applications (SPAs)")}} may paint first, and update the URL afterwards. When measuring {{Glossary("Largest contentful paint", "Largest Contentful Paint (LCP)")}} for {{Glossary("Soft navigation", "soft navigations")}} developers will want to include these paints, despite them happing before the URL updates. Since developers will not know if an interaction and a paint, may also result in a URL update and so a soft navigation, they would need to measure and buffer all `InteractionContentfulPaint` entries.


Suggested change

Some {{Glossary("SPA", "Single Page Applications (SPAs)")}} may paint first, and update the URL afterwards. When measuring {{Glossary("Largest contentful paint", "Largest Contentful Paint (LCP)")}} for {{Glossary("Soft navigation", "soft navigations")}} developers will want to include these paints, despite them happing before the URL updates. Since developers will not know if an interaction and a paint, may also result in a URL update and so a soft navigation, they would need to measure and buffer all `InteractionContentfulPaint` entries.

Some {{Glossary("SPA", "Single Page Applications (SPAs)")}} may paint first and update the URL afterwards. When measuring {{Glossary("Largest contentful paint", "Largest Contentful Paint (LCP)")}} for {{Glossary("Soft navigation", "soft navigations")}}, developers will want to include these paints despite them happening before the URL updates. Since developers will not know if an interaction and a paint will also result in a URL update and therefore a soft navigation, they would need to measure and buffer all `InteractionContentfulPaint` entries.

@mmocny suggested changes to this text so changed it to this:

Some {{Glossary("SPA", "Single Page Applications (SPAs)")}} may paint first, and update the URL afterwards. When measuring {{Glossary("Largest contentful paint", "Largest Contentful Paint (LCP)")}} for {{Glossary("Soft navigation", "soft navigations")}}, developers will want to include these paints, despite them happening before the URL updates. Because any interaction with any paints could in theory also lead to a URL update and thus soft navigation at any point in the future this could be difficult to measure without potentially saving a temporary reference to every interaction's LCP, should it be needed.

Let me know if you've any further changes.

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

chrisdavidmills

OK, @tunetheweb, a couple of last minute wording suggestions for the last round of changes.

If you are happy with these (and @mmocny is happy), then I'm happy.

…ulpaint/index.md Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

…ctioncontentfulpaint/index.md Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

chrisdavidmills

@tunetheweb, awesome, approving.

I'll just hold off on merging until @mmocny gives us an LGTM, too.

mmocny · 2026-08-12T12:31:26Z

LGTM, thanks for the updates! (I dont have access to formally Approve the PR)

chrisdavidmills · 2026-08-12T14:34:44Z

LGTM, thanks for the updates! (I dont have access to formally Approve the PR)

No worries, this is perfect. Let's do this!

tunetheweb · 2026-08-12T17:55:19Z

Gahhh just spotted this:

Fix here: #45106

Josh-Cena · 2026-08-14T17:15:37Z

+  }
+});
+observer.observe({ type: "interaction-contentful-paint", buffered: true });
+
+## Specifications
+


FYI, malformed Markdown in a few files (has been fixed)

Add Soft Navigation docs

96b9905

tunetheweb requested review from a team as code owners August 7, 2026 18:45

tunetheweb requested review from sideshowbarker and removed request for a team August 7, 2026 18:45

github-actions Bot added Content:WebAPI Web API docs Content:Glossary Glossary entries labels Aug 7, 2026

tunetheweb mentioned this pull request Aug 7, 2026

Add InteractionContentfulPaint and PerformanceSoftNavigation mdn/browser-compat-data#30195

Merged

github-actions Bot added the size/l [PR only] 501-1000 LoC changed label Aug 7, 2026

Fix linting

5c06fea

sideshowbarker requested review from chrisdavidmills and removed request for a team and sideshowbarker August 8, 2026 00:15

chrisdavidmills requested changes Aug 10, 2026

View reviewed changes

This comment was marked as duplicate.

Sign in to view

tunetheweb and others added 12 commits August 10, 2026 11:02

Update files/en-us/web/api/interactioncontentfulpaint/index.md

e977ec4

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

Apply suggestions from code review

ddcd1dd

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

Review feedback

06d69ad

Merge branch 'soft-navs' of github.com:tunetheweb/content into soft-navs

f837fcd

Update files/en-us/web/api/interactioncontentfulpaint/index.md

357b435

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

Update files/en-us/web/api/interactioncontentfulpaint/index.md

a9316b5

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

Apply suggestions from code review

ddbe14c

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

Apply suggestions from code review

948273d

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

Apply suggestions from code review

47a0ca4

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

Add contentful paint and update other entries

173597a

Update files/en-us/web/api/interactioncontentfulpaint/interactionid/i…

085f834

…ndex.md

Merge branch 'soft-navs' of github.com:tunetheweb/content into soft-navs

04ba3f1

tunetheweb added 8 commits August 10, 2026 12:39

Remove brackets from property

54722e3

tweaks

948f9d6

Tweaks to glossary

4d47b3f

More tweaks

db55b4b

More tweaks

6564baa

Tweaky, tweaky, tweaky

161467b

More tweaks

4c81831

Review feedback

591621e

mmocny reviewed Aug 11, 2026

View reviewed changes

chrisdavidmills requested changes Aug 11, 2026

View reviewed changes

tunetheweb and others added 3 commits August 11, 2026 15:57

Apply suggestions from code review

a5efd19

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

Review feedback

bb9c31d

Merge branch 'soft-navs' of github.com:tunetheweb/content into soft-navs

3dbc817

tunetheweb requested review from chrisdavidmills and mmocny August 11, 2026 15:01

tunetheweb commented Aug 11, 2026

View reviewed changes

Comment thread files/en-us/web/api/performancesoftnavigation/index.md Outdated

Apply suggestion from @tunetheweb

d090da6

chrisdavidmills requested changes Aug 12, 2026

View reviewed changes

Comment thread files/en-us/web/api/interactioncontentfulpaint/largestcontentfulpaint/index.md Outdated

Comment thread files/en-us/web/api/performancesoftnavigation/getlargestinteractioncontentfulpaint/index.md Outdated

tunetheweb and others added 3 commits August 12, 2026 12:18

Update files/en-us/web/api/interactioncontentfulpaint/largestcontentf…

9b4ada6

…ulpaint/index.md Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

Update files/en-us/web/api/performancesoftnavigation/getlargestintera…

9332fb4

…ctioncontentfulpaint/index.md Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

Merge branch 'main' into soft-navs

e157dc6

chrisdavidmills approved these changes Aug 12, 2026

View reviewed changes

chrisdavidmills merged commit 3f058f2 into mdn:main Aug 12, 2026
9 checks passed

tunetheweb mentioned this pull request Aug 12, 2026

Fix Contentful Paint SVG link #45106

Closed

Josh-Cena reviewed Aug 14, 2026

View reviewed changes

tunetheweb mentioned this pull request Aug 26, 2026

Improvements to Soft Navigation docs #45324

Merged


		The `getLargestInteractionContentfulPaint()` method of the {{domxref("PerformanceSoftNavigation")}} interface returns the current largest {{domxref("InteractionContentfulPaint")}} relevant to this soft navigation.

		Some {{Glossary("SPA", "Single Page Applications (SPAs)")}} may paint first, and update the URL afterwards. When measuring {{Glossary("Largest contentful paint", "Largest Contentful Paint (LCP)")}} for {{Glossary("Soft navigation", "soft navigations")}} developers will want to include these paints, despite them happing before the URL updates. Since developers will not know if an interaction and a paint, may also result in a URL update and so a soft navigation, they would need to measure and buffer all `InteractionContentfulPaint` entries.

Conversation

tunetheweb commented Aug 7, 2026

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tunetheweb commented Aug 7, 2026

Uh oh!

tunetheweb commented Aug 7, 2026

Uh oh!

chrisdavidmills left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as duplicate.

Uh oh!

tunetheweb commented Aug 10, 2026

Uh oh!

mmocny left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chrisdavidmills left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chrisdavidmills Aug 11, 2026

Choose a reason for hiding this comment

Uh oh!

tunetheweb Aug 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chrisdavidmills left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

chrisdavidmills left a comment

Choose a reason for hiding this comment

Uh oh!

mmocny commented Aug 12, 2026

Uh oh!

chrisdavidmills commented Aug 12, 2026

Uh oh!

Uh oh!

tunetheweb commented Aug 12, 2026

Uh oh!

Josh-Cena Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

github-actions Bot commented Aug 7, 2026 •

edited

Loading