Editorial review: Document PerformanceNavigationTiming.confidence by chrisdavidmills · Pull Request #43528 · mdn/content

chrisdavidmills · 2026-03-23T09:56:02Z

Description

Chrome 145 adds support for the PerformanceNavigationTiming.confidence property, and the associated PerformanceTimingConfidence interface. See https://chromestatus.com/feature/5186950448283648.

This PR adds documentation for both features mentioned above.

Motivation

Additional details

Related issues and pull requests

github-actions · 2026-03-23T09:57:44Z

Preview URLs (7 pages)

(comment last updated: 2026-03-27 16:40:45)

hamishwillee · 2026-03-23T22:36:23Z

@chrisdavidmills This says "technical review". Is it ready for me to look at?

chrisdavidmills · 2026-03-24T08:22:22Z

@chrisdavidmills This says "technical review". Is it ready for me to look at?

@hamishwillee. Not yet; I requested a tech review from the browser engineers yesterday. Once it is ready, I'll flip it to "Editorial review".

mmocny

The docs look great, thanks for doing it!

I'm not the primary engineering contact for this, so hopefully Mike Jackson at Msft will have a change to take a look.

One detail that is missing from the docs: how should you use this value and interpret the data on the server? This feels like the most important part of the API, and also the harder to understand for developers.

Mike has done some presentations on this, and I see that he added a NOTE to the very bottom of this spection of the spec: https://www.w3.org/TR/navigation-timing-2/#sec-PerformanceNavigationTiming

This section is intended to help RUM providers and developers interpret confidence

...that section might be worth including in docs here?

Cheers.

mmocny · 2026-03-26T20:14:12Z

files/en-us/web/api/performancenavigationtiming/confidence/index.md

+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`confidence`** read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be representative of the current user's device.


"representative of the current user's device"

I see that this wording comes from the navigation timing spec itself. Personally, I don't like that phrasing.

It's more like "known to have adverse conditions affecting performance" or something.

I think its fine to leave to match spec, but maybe Mike Jackson wants to take the chance to wordsmith?

Maybe something like: returned navigation metrics free from external system load unrelated to the page.

I like @mwjacksonmsft's wording; I'll update the wording to that in the places where it appears.

mmocny · 2026-03-26T20:15:17Z

files/en-us/web/api/performancenavigationtiming/confidence/index.md

+
+The **`confidence`** read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be representative of the current user's device.
+
+For example, if the browser has launched from a "cold start" before loading a website or has resource-intensive extensions running, or if other applications running on the user's device are taking up a lot of resource cycles, web pages may load more slowly as a result. In such cases, a `low` confidence {{domxref("PerformanceTimingConfidence.value", "value")}} would be returned.


Some of these are aspirational right now.

Should we make it clearer what is actually (I think cold startup?) vs might one day be affecting?

Mike is the expert.

At the moment, this works for cold start, and session restore. I'd prefer that we only highlight those items (or call out that the others are potential future cases and not currently implemented).

I've updated the wording on both pages it appears on to:

For example, if a website has loaded after a browser "cold start" or session restore, its pages may load more slowly as a result.

mwjacksonmsft · 2026-03-27T06:30:39Z

files/en-us/web/api/performancenavigationtiming/index.md

 - {{domxref('PerformanceNavigationTiming.activationStart')}} {{ReadOnlyInline}} {{experimental_inline}}
  - : A {{domxref("DOMHighResTimeStamp")}} representing the time between when a document starts prerendering and when it is activated.
+- {{domxref('PerformanceNavigationTiming.confidence')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be representative of the current user's device.


Should we adjust the language here as well to match confidence/index.md?

Good call; done.

mwjacksonmsft · 2026-03-27T06:31:40Z

files/en-us/web/api/performancetimingconfidence/value/index.md

+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`value`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is an enumerated value indicating a broad confidence measure of whether the user agent considers returned navigation metrics to be representative of the current user's device.


Same question here - should we update this to match the verbiage in confidence/index.md

chrisdavidmills · 2026-03-27T16:16:04Z

Mike has done some presentations on this, and I see that he added a NOTE to the very bottom of this section of the spec: https://www.w3.org/TR/navigation-timing-2/#sec-PerformanceNavigationTiming

This section is intended to help RUM providers and developers interpret confidence

...that section might be worth including in docs here?

This makes sense. For the moment, I've gone for including all the text in this section in the PerformanceTimingConfidence page, under a heading of "Interpreting confidence data". I've not made many changes, except for a few tweaks, and adding links to the different values.

Anyway, I'll include that in my next commit.

mwjacksonmsft

These changes LGTM. Thanks!

chrisdavidmills · 2026-03-27T17:21:38Z

Cool, thanks, @mwjacksonmsft. I'll move this to the editorial review stage.

@hamishwillee, ready for you to have a look, if you've still got time early next week.

Document PerformanceNavigationTiming.confidence

2fbad3b

chrisdavidmills requested a review from a team as a code owner March 23, 2026 09:56

chrisdavidmills requested review from hamishwillee and removed request for a team March 23, 2026 09:56

github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Mar 23, 2026

chrisdavidmills changed the title ~~Document PerformanceNavigationTiming.confidence~~ Technical review: Document PerformanceNavigationTiming.confidence Mar 23, 2026

mmocny reviewed Mar 26, 2026

View reviewed changes

mwjacksonmsft reviewed Mar 27, 2026

View reviewed changes

Merge branch 'main' into performancenavigationtiming-confidence

cef856f

Fixes for technical review comments

2930c97

chrisdavidmills requested review from mmocny and mwjacksonmsft March 27, 2026 16:39

mwjacksonmsft reviewed Mar 27, 2026

View reviewed changes

chrisdavidmills changed the title ~~Technical review: Document PerformanceNavigationTiming.confidence~~ Editorial review: Document PerformanceNavigationTiming.confidence Mar 27, 2026


		{{APIRef("Performance API")}}{{SeeCompatTable}}

		The `confidence` read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be representative of the current user's device.


		The `confidence` read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be representative of the current user's device.

		For example, if the browser has launched from a "cold start" before loading a website or has resource-intensive extensions running, or if other applications running on the user's device are taking up a lot of resource cycles, web pages may load more slowly as a result. In such cases, a `low` confidence {{domxref("PerformanceTimingConfidence.value", "value")}} would be returned.


		{{APIRef("Performance API")}}{{SeeCompatTable}}

		The `value` read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is an enumerated value indicating a broad confidence measure of whether the user agent considers returned navigation metrics to be representative of the current user's device.

Conversation

chrisdavidmills commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hamishwillee commented Mar 23, 2026

Uh oh!

chrisdavidmills commented Mar 24, 2026

Uh oh!

mmocny left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisdavidmills Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisdavidmills commented Mar 27, 2026

Uh oh!

mwjacksonmsft left a comment

Choose a reason for hiding this comment

Uh oh!

chrisdavidmills commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

chrisdavidmills commented Mar 23, 2026 •

edited

Loading

github-actions bot commented Mar 23, 2026 •

edited

Loading

chrisdavidmills Mar 27, 2026 •

edited

Loading