diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index b1ded9a82a5494f..94d43660985e10a 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -9137,6 +9137,7 @@ /en-US/docs/Web/API/OverconstrainedError/name /en-US/docs/Web/API/DOMException/name /en-US/docs/Web/API/PaintWorklet/PaintWorklet.devicePixelRatio /en-US/docs/Web/API/PaintWorklet/devicePixelRatio /en-US/docs/Web/API/PaintWorklet/devicePizelRatio /en-US/docs/Web/API/PaintWorklet/devicePixelRatio +/en-US/docs/Web/API/Paint_Timing_API /en-US/docs/Web/API/PerformancePaintTiming /en-US/docs/Web/API/PannerNode.coneInnerAngle /en-US/docs/Web/API/PannerNode/coneInnerAngle /en-US/docs/Web/API/PannerNode.coneOuterAngle /en-US/docs/Web/API/PannerNode/coneOuterAngle /en-US/docs/Web/API/PannerNode.coneOuterGain /en-US/docs/Web/API/PannerNode/coneOuterGain diff --git a/files/en-us/glossary/first_contentful_paint/index.md b/files/en-us/glossary/first_contentful_paint/index.md index 01012eb89215f9f..9adfbe73f33db06 100644 --- a/files/en-us/glossary/first_contentful_paint/index.md +++ b/files/en-us/glossary/first_contentful_paint/index.md @@ -14,7 +14,7 @@ _The First Contentful Paint_ time stamp is when the browser first rendered any t ## See also - [First paint](/en-US/docs/Glossary/First_paint) -- [Paint Timing API](/en-US/docs/Web/API/Paint_Timing_API) +- [`PerformancePaintTiming`](/en-US/docs/Web/API/PerformancePaintTiming) - [Largest Contentful API](/en-US/docs/Web/API/Largest_Contentful_Paint_API) - [First meaningful paint](/en-US/docs/Glossary/first_meaningful_paint) - [First Contentful Paint](https://web.dev/fcp/) at web.dev diff --git a/files/en-us/glossary/first_paint/index.md b/files/en-us/glossary/first_paint/index.md index bfe25bfa3ec0bed..cfeea26335b759c 100644 --- a/files/en-us/glossary/first_paint/index.md +++ b/files/en-us/glossary/first_paint/index.md @@ -7,11 +7,11 @@ tags: - Web Performance --- -**First Paint**, part of the [Paint Timing API](/en-US/docs/Web/API/Paint_Timing_API), is the time between navigation and when the browser renders the first pixels to the screen, rendering anything that is visually different from the default [background color](/en-US/docs/Web/CSS/background-color) of the [body](/en-US/docs/Web/API/Document/body). It answers the question "Is it happening?" +**First Paint** is the time between navigation and when the browser first renders pixels to the screen, rendering anything that is visually different from the default [background color](/en-US/docs/Web/CSS/background-color) of the [body](/en-US/docs/Web/API/Document/body). It is the first key moment in page load and will answer the question "Has the browser started to render the page?" ## See also - [First contentful paint](/en-US/docs/Glossary/First_contentful_paint) -- [Paint Timing API](/en-US/docs/Web/API/Paint_Timing_API) +- [`PerformancePaintTiming`](/en-US/docs/Web/API/PerformancePaintTiming) - [Largest Contentful API](/en-US/docs/Web/API/Largest_Contentful_Paint_API) - [First meaningful paint](/en-US/docs/Glossary/first_meaningful_paint) diff --git a/files/en-us/web/api/paint_timing_api/index.md b/files/en-us/web/api/paint_timing_api/index.md deleted file mode 100644 index a28eb798de01f32..000000000000000 --- a/files/en-us/web/api/paint_timing_api/index.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Paint Timing API -slug: Web/API/Paint_Timing_API -page-type: web-api-overview -tags: - - API - - Paint Timing API - - Performance - - PerformancePaintTiming - - Landing - - Overview - - Reference -browser-compat: api.PerformancePaintTiming ---- - -{{DefaultAPISidebar("Performance API")}} - -The **Paint Timing API** provides [perceived performance](/en-US/docs/Learn/Performance/Perceived_performance) data that allows you to know exactly how long a user waits, after navigating to your page, before seeing any of the page content at all (which may not yet be the main content) first starting to appear. More specifically, it allows you to know exactly when, during page load, {{Glossary("first paint")}} and {{Glossary("first contentful paint")}} occur. - -The [Largest Contentful Paint API](/en-US/docs/Web/API/Largest_Contentful_Paint_API) is a closely-related API that allows you to know exactly how long a user waits before they can see the **main content** of your page in the browser viewport — in contrast to just knowing when the user can see what may be a loading indicator or background image or other such initial/early-loading content (which is what the Paint Timing API provides). - -## Concepts and usage - -The key principle underlying the Paint Timing API is that by having data to help you minimize the time that users have to wait before they can see the site's content start to appear, you can make the site feel more engaging and responsive (better performing) for your users. - -See the [perceived performance](/en-US/docs/Learn/Performance/Perceived_performance) article for an introduction to the core concepts underlying both the Paint Timing API and the [Largest Contentful Paint API](/en-US/docs/Web/API/Largest_Contentful_Paint_API). - -## Interfaces - -- {{domxref('PerformancePaintTiming')}} - - : Extends the {{domxref('PerformanceEntry')}} interface with the additional {{domxref('PerformanceEntry.entryType', 'entryType')}} value `"paint"` and the two additional {{domxref('PerformanceEntry.name', 'name')}} values `"first-paint"` and `"first-contentful-paint"`. - -## Examples - -See the {{domxref('PerformancePaintTiming')}} article for an example of using the Paint Timing API. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [First paint](/en-US/docs/Glossary/First_paint) -- [First contentful paint](/en-US/docs/Glossary/First_contentful_paint) -- [Largest Contentful API](/en-US/docs/Web/API/Largest_Contentful_Paint_API) -- [Perceived performance](/en-US/docs/Learn/Performance/Perceived_performance) -- [User-centric performance metrics](https://web.dev/user-centric-performance-metrics/#types-of-metrics) at web.dev diff --git a/files/en-us/web/api/performancepainttiming/index.md b/files/en-us/web/api/performancepainttiming/index.md index 892fe3a8a3f5207..b722964a2bac007 100644 --- a/files/en-us/web/api/performancepainttiming/index.md +++ b/files/en-us/web/api/performancepainttiming/index.md @@ -2,28 +2,31 @@ title: PerformancePaintTiming slug: Web/API/PerformancePaintTiming page-type: web-api-interface -tags: - - API - - Interface - - Paint Timing - - Performance Timeline API - - PerformancePaintTiming - - Reference - - Web Performance browser-compat: api.PerformancePaintTiming --- {{APIRef("Performance API")}} -The **`PerformancePaintTiming`** interface of the [Paint Timing API](/en-US/docs/Web/API/Paint_Timing_API) provides timing information about "paint" (also called "render") operations during web page construction. "Paint" refers to conversion of the render tree to on-screen pixels. +The **`PerformancePaintTiming`** interface provides timing information about "paint" (also called "render") operations during web page construction. "Paint" refers to conversion of the render tree to on-screen pixels. -An application can register a {{domxref("PerformanceObserver")}} for "`paint`" {{domxref("PerformanceEntry","performance entry types")}} and the observer can retrieve the times that paint events occur. Use this information to help identify areas that take too long to provide a good user experience. +There are two key paint moments this API provides: + +- {{Glossary("First paint")}} (FP): Time when anything is rendered. Note that the marking of the first paint is optional, not all user agents report it. +- {{Glossary("First contentful paint")}} (FCP): Time when the first bit of DOM text or image content is rendered. + +A third key paint moment is provided by the {{domxref("LargestContentfulPaint")}} API: + +- {{Glossary("Largest contentful paint")}} (LCP): Render time of the largest image or text block visible within the viewport, recorded from when the page first begins to load. + +The data this API provides helps you minimize the time that users have to wait before they can see the site's content start to appear. Decreasing the time until these key paint moments make sites feel more responsive, performant, and engaging for your users. + +Like other Performance APIs, this API extends {{domxref("PerformanceEntry")}}. {{InheritanceDiagram}} ## Instance properties -This interface has no properties but it extends the following {{domxref("PerformanceEntry")}} properties (for "`paint`" {{domxref ("PerformanceEntry.entryType","performance entry types")}}) by qualifying and constraining the properties as follows: +This interface has no properties but it extends the following {{domxref("PerformanceEntry")}} properties by qualifying and constraining the properties as follows: - {{domxref("PerformanceEntry.entryType")}} - : Returns "`paint`". @@ -38,27 +41,35 @@ This interface has no properties but it extends the following {{domxref("Perform This interface has no methods. -## Example +## Examples + +### Getting paint timings + +Example using a {{domxref("PerformanceObserver")}}, which notifies of new `paint` performance entries as they are recorded in the browser's performance timeline. Use the `buffered` option to access entries from before the observer creation. ```js -function showPaintTimings() { - if (window.performance) { - let performance = window.performance; - let performanceEntries = performance.getEntriesByType('paint'); - performanceEntries.forEach((performanceEntry) => { - console.log(`The time to ${performanceEntry.name} was ${performanceEntry.startTime} milliseconds.`); - }); - } else { - console.log('Performance timing isn\'t supported.'); - } -} +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + console.log( + `The time to ${entry.name} was ${entry.startTime} milliseconds.` + ); + // Logs "The time to first-paint was 386.7999999523163 milliseconds." + // Logs "The time to first-contentful-paint was 400.6999999284744 milliseconds." + }); +}); + +observer.observe({ type: "paint", buffered: true }); ``` -The code above produces console output something like the following: +Example using {{domxref("Performance.getEntriesByType()")}}, which only shows `paint` performance entries present in the browser's performance timeline at the time you call this method: -```bash -The time to first-paint was 2785.915 milliseconds. -The time to first-contentful-paint was 2787.460 milliseconds. +```js +const entries = performance.getEntriesByType("paint"); +entries.forEach((entry) => { + console.log(`The time to ${entry.name} was ${entry.startTime} milliseconds.`); + // Logs "The time to first-paint was 386.7999999523163 milliseconds." + // Logs "The time to first-contentful-paint was 400.6999999284744 milliseconds." +}); ``` ## Specifications @@ -68,3 +79,7 @@ The time to first-contentful-paint was 2787.460 milliseconds. ## Browser compatibility {{Compat}} + +### See also + +- {{domxref("LargestContentfulPaint")}} diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index a7e13dafa48bd64..4acb9aa7c8107da 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -935,7 +935,6 @@ "/docs/Web/API/User_timing_API", "/docs/Web/API/User_timing_API/Using_the_User_Timing_API", "/docs/Web/API/Element_timing_API", - "/docs/Web/API/Paint_timing_API", "/docs/Web/API/Largest_Contentful_Paint_API" ], "interfaces": [