useDebugValue

React useDebugValue: Inspecting Custom Hooks in DevTools

useDebugValue is a lightweight developer-experience Hook that displays a custom label beside your Custom Hook inside the React Developer Tools component inspector. It never affects rendered JSX or user-facing behavior—it purely helps engineers debug shared libraries and complex custom hooks faster.

Adding Readable Labels to Custom Hooks

Call useDebugValue(value) inside a Custom Hook. Whenever someone inspects a component using that hook in React DevTools, the label appears right next to the hook name.

import { useDebugValue, useEffect, useState } from 'react';

export function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(() => navigator.onLine);

  useEffect(() => {
    const goOnline = () => setIsOnline(true);
    const goOffline = () => setIsOnline(false);

    window.addEventListener('online', goOnline);
    window.addEventListener('offline', goOffline);
    return () => {
      window.removeEventListener('online', goOnline);
      window.removeEventListener('offline', goOffline);
    };
  }, []);

  useDebugValue(isOnline ? 'Online' : 'Offline');
  return isOnline;
}

Lazy Formatting for Expensive Debug Output

If formatting your debug label requires calling JSON.stringify or toLocaleDateString(), pass a formatter function as the second argument: useDebugValue(date, (d) => d.toISOString()). React runs that formatter function only when React DevTools is actively open and inspecting the component, keeping normal development renders fast.

Common useDebugValue Mistakes

• Adding useDebugValue to Every Small Hook: Hooks that hold a single boolean or string already show their state in DevTools. Save useDebugValue for shared design-system hooks or hooks combining multiple internal states.
• Calling useDebugValue Directly in Regular Components: useDebugValue is only useful inside Custom Hooks; regular components already display their own state and props in DevTools.

Frequently Asked Questions

Does useDebugValue slow down production users?

No. In production builds, React does not run the DevTools formatter callback, and simple label values carry negligible cost.

Can I pass an object instead of a string to useDebugValue?

Yes. React DevTools renders inspectable objects and arrays beside the hook entry, though short summary strings are fastest to scan.

Where do I see useDebugValue output?

Open Chrome or Firefox DevTools, switch to the Components tab from React Developer Tools, click a component, and inspect the Hooks section on the right.