first-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—, , , 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

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:

``sh
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

`js
import {start} from "first-important-paint";
start();
`

You can then mark _important_ elements using the important attribute.

index.html

`html



`

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.

`js
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

FAQ

$3

Yes, it is supported on any JavaScript framework, including ReactJS.

$3

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.

$3

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