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.
import { Profiler } from 'react'; <Profiler id="Sidebar" onRender={onRender}> <Sidebar /> </Profiler>
Try it
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
<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/profilingentry), 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
actualDurationis much smaller thanbaseDuration, 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.
Related
- StrictMode, memo, useMemo
- Lessons: Profiling React apps, Memo