Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Components and Special Elements

The Profiler component

Reference for the React Profiler component: measure how long a tree takes to render, read the onRender arguments, and know when profiling is available.

Profiler measures how often a part of your component tree renders and how much time those renders cost. You wrap the tree you care about, give the wrapper an id and an onRender callback, and React calls the callback every time something inside commits an update.

It is the programmatic sibling of the Profiler tab in React DevTools. Use the DevTools to explore interactively; use the component when you want numbers in code: logging slow commits in a test, sending timings to a monitoring service from a staging build, or comparing two implementations.

JSX
import { Profiler } from 'react';

<Profiler id="Sidebar" onRender={onRender}>
  <Sidebar />
</Profiler>

Try it

Log every commit
Two profilers, one updates

The console shows header: mount and list: mount first. Each click on Add item adds only list: update: App does not re-render, so the header profiler stays quiet. A profiler reports when its own subtree is rendered again, which includes the case where the component that contains it re-renders, even if everything inside is memoized.

Syntax

JSX
<Profiler id={string} onRender={callback}>{children}</Profiler>

function onRender(id, phase, actualDuration, baseDuration, startTime, commitTime) {}
Name Description
id A string that identifies the tree being measured. Shows up as the first argument of the callback.
onRender Called each time a component inside the profiled tree commits an update.
children The tree to measure.

Arguments of onRender:

Argument Description
id The id prop of the Profiler that fired.
phase "mount" on the first render, "update" on later re-renders, "nested-update" when caused by an update scheduled from a layout effect or a similar commit-phase callback.
actualDuration Milliseconds spent rendering the profiled tree for this update. Shrinks when memoization works.
baseDuration Estimated milliseconds to render the whole subtree without any memoization: a worst-case estimate.
startTime Timestamp when React began rendering this update.
commitTime Timestamp when React committed this update. Shared by all profilers in the same commit.

Errors: none are thrown by the component itself. A Profiler without an id or onRender warns in development.

Usage notes

  • Availability. Profiling is on in development builds and disabled in standard production builds because the timing adds overhead. To measure a production-like build, use React's profiling build (the react-dom/profiling entry), which most bundlers expose through an alias.
  • Cost of nesting. Profilers add a small overhead per wrapper. Add them where you need data and remove them when you are done; do not wrap every component permanently.
  • Several profilers are fine and can be nested. Each reports only its own subtree. A change below an inner profiler also triggers every outer one.
  • Reading the numbers. If actualDuration is much smaller than baseDuration, memoization is paying off. If they are nearly equal on every update, nothing is being skipped.
  • Timings are not deterministic. They vary with the machine, the browser, JIT warm-up and other work on the page. Compare averages, not single values, and never assert exact times in tests.
  • Do not set state in onRender. It runs during the commit phase, and updating state there creates a loop of extra renders.
  • Callback runs on each commit, not each render. Renders that React abandons do not report.