React Reference ยท State Hooks
React useDebugValue hook
Reference for React useDebugValue: add a readable label to a custom hook in React DevTools, with an optional formatter so expensive formatting runs only on inspection.
useDebugValue attaches a label to a custom hook. The label appears next to the hook's name when you inspect a component in React DevTools. It has no effect on rendering, state or output, and in production it does nothing visible.
Use it in shared custom hooks, where the raw internals (State, Effect, Ref) say little about what the hook is doing. A label like FriendStatus: Online turns an anonymous list of hooks into something readable.
function useOnlineStatus() { const isOnline = /* ... */; useDebugValue(isOnline ? 'Online' : 'Offline'); return isOnline; }
Try it
The page output is unchanged; the label is only visible in the DevTools Components panel.
Without DevTools open, the formatter is never called, so the counter stays at 0.
Syntax
useDebugValue(value); useDebugValue(value, format);
function useDebugValue<T>(value: T, format?: (value: T) => any): void;
| Name | Description |
|---|---|
value |
The value DevTools shows next to the hook. |
format |
Optional. A function that turns value into the displayed label. React DevTools calls it only when the component is inspected. |
Returns: nothing (undefined).
Usage notes
- Only inside hooks. Call it from a custom hook (or a component), at the top level, like any hook. It is most useful in hooks you publish or share.
- No effect on the app. It never changes behavior or output, so you can add it freely while debugging.
- Use the formatter for costly labels. A label like a
Dateformatted for display, or a large object summary, should be computed informatso no work happens unless someone inspects. - Don't add it to every hook. Local hooks used once are usually clear enough from their name and the component code.
- Visible only in DevTools. It does not log to the console and is not rendered in the page.
- Not a logging tool: to trace values over time use
console.login an effect or the DevTools profiler.
Related
- useState, useId, useEffect
- Lessons: Custom hooks, Debugging React