first-important-paint
v0.2.0first-important-paint
First Important Paint (FIP) measures the time taken to paint the first important element to screen.
Largest Contentful Paint (LCP) measures the time it takes to paint the largest element—<img>
, <image>
, <video>
, CSS's background-image
and text elements—to screen. However, the largest element is not always the most important one. If the most important element is a <table>
consisting of multiple smaller elements; then the LCP metric may not be representative of the user experience.
First Important Paint aims to solve that limitation by allowing you to measure the timing for any element using requestAnimationFrame
and checking when an element is visible on the page. It can be used in combination with LCP and the Element Timing API.
FIP works on all modern browsers, including Safari.
Installation:
npm -i -s first-important-paint
Usage
To begin measuring First Important Paint you are required to import the first-important-paint
as early as possible in your application's JavaScript file.
main.js
import {start} from "first-important-paint";
start();
You can then mark important elements using the important
attribute.
index.html
<div important>
<ul>
<li>Item #1</li>
<li>Item #2</li>
</ul>
</div>
When the first important
element is rendered on screen, the browser will create a performance.mark
entry with the name first-important-paint
. This is visible on DevTools and can be retrieved later using the PerformanceObserver
.
new PerformanceObserver((entryList) => {
for (const entry of entryList.getEntries()) {
if (entry.name === "first-important-paint") {
console.log(entry);
const { name, startTime, detail } = entry;
const { id, nodeName, src } = detail;
// Test sending the metric to an analytics endpoint.
navigator.sendBeacon(
`/collect`,
JSON.stringify({entryType: "first-important-paint", renderTime: startTime, id, nodeName, url: src})
);
}
}
}).observe({ type: "mark", buffered: true });
Options
You can override the default configurations by passing parameters to the start
method. Below are the supported options:
Option | Type | Description |
---|---|---|
markName |
string | The name to be used when creating the performance.mark (Default: first-important-paint ) |
selector |
string | The CSS selector to use to identify important elements. (Default: [important] ) |
timeout |
number | The maximum time, in milliseconds, to search for the element. (Default: 60000 ) |
Quality
To check the quality of the metric, I ran several tests and document my research.
The tests indicate that FIP correlates with LCP and Element Timing and is stable and elastic, but tends to underreport.
Known limitations
- FIP will wait for all fonts to finish downloading. This means that if the element you are measuring does not use any fonts but other elements on the page do, then it will not fire until all fonts have finished downloading.
- If the FIP element is offscreen it will still be reported.
- It is not tested on
<video>
elements. - When a
<picture>
element is marked asimportant
, the metric will correctly measure the time the<picture>
element renders but will log thesrc
of the<img>
not necessarily the image rendered. - FIP does not factor in the GPU.
FAQ
Can I use it with ReactJS?
Yes, it is supported on any JavaScript framework, including ReactJS.
Is there a performance overhead when using FIP?
FIP was developed with minimal overhead. It uses requestAnimationFrame
and postmessage
, does not block the main thread, and is less than 1KB minified. My tests indicate that it has no impact on LCP.
Which browsers are supported?
Supported on all major browsers, including Chrome, Firefox and Safari. CanIUse data.
Contributing
Anyone and everyone is welcome to contribute to this project and leave feedback. Please take a moment to review the guidelines for contributing.
License and Copyright
This software is released under the terms of the MIT license.
- Photo by Ferenc Horvath on Unsplash.
- Video by Michal Marek
Metadata
- MIT
- Whatever
- Kevin Farrugia
- released 3/9/2022