How to Debug useDebugValue Hook in React

The useDebugValue Hook is a built-in React Hook that allows developers to display custom, readable labels for custom Hooks inside React Developer Tools. This article explains how to implement useDebugValue in your custom Hooks, how to view and debug these values using React Developer Tools, and how to optimize performance using deferred formatting.

Understanding useDebugValue

In React, custom Hooks are a powerful way to share stateful logic. However, as your application grows, tracking the internal state of these Hooks can become difficult. While you can use console.log, React provides the useDebugValue Hook specifically to output debug information directly to the React Developer Tools extension, keeping your console clean and your debugging workflow organized.

It is important to note that useDebugValue should only be called inside custom Hooks. Calling it inside standard functional components will not yield any results.

Step-by-Step Guide to Debugging with useDebugValue

To inspect and debug the output of useDebugValue, follow these steps:

1. Implement the Hook in a Custom Hook

First, import useDebugValue from React and call it inside your custom Hook. Pass the value you want to monitor as the argument.

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

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

  useEffect(() => {
    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);

    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []);

  // Display "Online" or "Offline" in React DevTools
  useDebugValue(isOnline ? 'Online' : 'Offline');

  return isOnline;
}

2. Open React Developer Tools

To see the debug label, you must use the React Developer Tools browser extension (available for Chrome, Firefox, and Edge).

  1. Open your browser’s Developer Tools (F12 or right-click and select Inspect).
  2. Navigate to the Components tab.
  3. Select the component that consumes your custom Hook (e.g., useOnlineStatus).

3. Inspect the Custom Hook State

In the right-hand panel of the Components tab, look under the Hooks section. You will see your custom Hook listed with the debug value displayed directly next to it:

⚙️ Hooks
  ↳ OnlineStatus: "Online"

If you change the state (such as toggling your internet connection), the debug value will update in real-time in the DevTools interface.

Optimizing Performance with Deferred Formatting

In some cases, formatting a value for display in the DevTools can be computationally expensive (for example, parsing a large date object or formatting an array). Because useDebugValue runs on every render, it can slow down your application in development mode.

To prevent this, useDebugValue accepts an optional second argument: a formatting function. This function only runs when the React Developer Tools are actually open and the component is inspected.

useDebugValue(timestamp, date => new Date(date).toUTCString());

In this example, the slow toUTCString() operation is deferred. It will not execute during standard app rendering unless you are actively inspecting the component in the DevTools.