next-element-timing

Measure when specific elements in a Next.js app appear, paint, and become interactive, meaning React has hydrated them and their event handlers will respond. Send the timings to New Relic, Dynatrace or your own analytics.

This guide is for Next.js 16.3+ with the App Router. Using the Pages Router, or an older Next.js? See Pages Router or Older Next.js and React versions.

Quick start

npm install next-element-timing

1. Load the client module before hydration by wrapping your Next.js config:

// next.config.ts
import { withElementTiming } from "next-element-timing/next";

export default withElementTiming({
  /* your config */
});

Client-side navigations are tracked automatically, so each page's timings start from the navigation that rendered it.

2. Tag the elements you want to time. In client components, spread timingProps:

"use client";
import { timingProps } from "next-element-timing";

<button {...timingProps("add-to-bag")} onClick={add}>Add to bag</button>

In server components you can't pass a ref, so add the two attributes directly:

<Link href="/" data-timing="logo" elementtiming="logo">Home</Link>

3. See the timings. Add the overlay to your root layout while you're developing (disable in production):

// app/layout.tsx
import { TimingPanel } from "next-element-timing/panel";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <TimingPanel />
      </body>
    </html>
  );
}

Load a page and the panel lists each tagged element with its Present, Paint and Live times in milliseconds since the navigation.

Time an element from a click

To measure how long element B takes to show up after a user clicks button A, list B's name on A:

<button {...timingProps("open-cart", { until: "cart" })} onClick={openCart}>Cart</button>

{open && <aside {...timingProps("cart")}>…</aside>}

In server components, add data-timing-until="cart" alongside data-timing. To time several elements from one click, separate their names with spaces.

The next element named cart to appear after the click carries trigger: "open-cart" and sinceTrigger on each of its phases. present tells you when it appeared, and interactive when it appeared and its handlers were live. The panel shows these as an open-cart → cart row timed from the click. The click time is the browser's timestamp for the input, so it includes any wait for the main thread or for hydration.

• B must appear after the click. An element that was already on the page doesn't count, so give content that updates in place a React key that changes, so it remounts.
• Only the first matching element after each click counts, and a click whose element hasn't appeared within 30 seconds is dropped. A click survives navigation, so a link can time an element on the next page.
• For interactions other than clicks, call startTrigger("search", ["results"]) yourself.

Send timings to your monitoring tool

Each of these is independent; follow only the one you use:

• New Relic: one line, using the browser agent you already have.
• Dynatrace: allow-list six properties (eight if you use triggers), then one line.
• Anything else: your own analytics endpoint or another tool.

What gets measured

| Phase | Source | How it's measured | | ------------- | ----------------- | ----------------------------------------------------------------------------------- | | present | dom | When the element is in the DOM. For server-rendered HTML, when the client module ran (an upper bound). | | paint | element-timing | When the browser painted it, from the Element Timing API. Chromium only; needs the elementtiming attribute. | | interactive | hook | When the timingProps ref fires, in React's commit phase. Uses only supported React APIs. | | interactive | react-internals | Polls every 16 ms for an on* handler in React's private props. Works without timingProps, but relies on React internals and may break on upgrade. |

Every event has sinceNavigation: milliseconds since the initial page load or the client-side navigation that rendered the element. Elements timed from a click also have trigger and sinceTrigger; see Time an element from a click.

Caveats

• Background tabs throttle timers (to about 1 s in Chrome) and don't paint, so react-internals and paint times from hidden tabs are inflated.
• Each (element, phase, source) is recorded once. Elements that persist across client navigations, such as a header, are not re-recorded.
• Monitoring tools stamp events when they receive them, which can be later than they happened. See Timestamps.

More

• Pages Router and older Next.js and React versions
• Custom integrations and the full API
• Timestamps in monitoring tools
• Contributing: building, testing and the live vendor harness

License

MIT