React useDebugValue Hook Guide

The useDebugValue hook displays custom labels for hooks in React DevTools. Here's how to use it effectively.

Basic Usage#

import { useDebugValue, useState } from 'react';

function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(true);

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

  return isOnline;
}

// In DevTools: OnlineStatus: "Online"

With Custom Hooks#

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

function useLocalStorage<T>(key: string, initialValue: T) {
  const [value, setValue] = useState<T>(() => {
    const stored = localStorage.getItem(key);
    return stored ? JSON.parse(stored) : initialValue;
  });

  useEffect(() => {
    localStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);

  // Show key and value in DevTools
  useDebugValue(`${key}: ${JSON.stringify(value)}`);

  return [value, setValue] as const;
}

// In DevTools: LocalStorage: "theme: \"dark\""

Deferred Formatting#

import { useDebugValue, useState } from 'react';

interface User {
  id: string;
  name: string;
  email: string;
  lastLogin: Date;
}

function useUser(userId: string) {
  const [user, setUser] = useState<User | null>(null);

  // Expensive formatting only runs when DevTools is open
  useDebugValue(user, (user) => {
    if (!user) return 'No user';
    return `${user.name} (${user.email}) - Last: ${user.lastLogin.toLocaleDateString()}`;
  });

  return user;
}

// Formatting function only called when inspecting in DevTools

Multiple Debug Values#

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

interface FetchState<T> {
  data: T | null;
  loading: boolean;
  error: Error | null;
}

function useFetch<T>(url: string) {
  const [state, setState] = useState<FetchState<T>>({
    data: null,
    loading: true,
    error: null,
  });

  useEffect(() => {
    const controller = new AbortController();

    fetch(url, { signal: controller.signal })
      .then((res) => res.json())
      .then((data) => setState({ data, loading: false, error: null }))
      .catch((error) => {
        if (error.name !== 'AbortError') {
          setState({ data: null, loading: false, error });
        }
      });

    return () => controller.abort();
  }, [url]);

  // Show comprehensive state in DevTools
  useDebugValue(state, ({ data, loading, error }) => {
    if (loading) return 'Loading...';
    if (error) return `Error: ${error.message}`;
    return `Loaded: ${JSON.stringify(data).slice(0, 50)}...`;
  });

  return state;
}

Authentication Hook#

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

interface AuthState {
  user: User | null;
  isAuthenticated: boolean;
  isLoading: boolean;
}

function useAuth() {
  const [state, setState] = useState<AuthState>({
    user: null,
    isAuthenticated: false,
    isLoading: true,
  });

  useDebugValue(state, ({ user, isAuthenticated, isLoading }) => {
    if (isLoading) return 'Checking auth...';
    if (!isAuthenticated) return 'Not authenticated';
    return `Authenticated as ${user?.name}`;
  });

  // Auth logic...

  return state;
}

// In DevTools: Auth: "Authenticated as John Doe"

Form State Hook#

import { useDebugValue, useState } from 'react';

interface FormState<T> {
  values: T;
  errors: Partial<Record<keyof T, string>>;
  touched: Partial<Record<keyof T, boolean>>;
  isValid: boolean;
  isDirty: boolean;
}

function useForm<T extends Record<string, any>>(initialValues: T) {
  const [state, setState] = useState<FormState<T>>({
    values: initialValues,
    errors: {},
    touched: {},
    isValid: true,
    isDirty: false,
  });

  useDebugValue(state, ({ isValid, isDirty, errors }) => {
    const errorCount = Object.keys(errors).length;
    return `${isDirty ? 'Dirty' : 'Clean'}, ${isValid ? 'Valid' : `${errorCount} errors`}`;
  });

  // Form logic...

  return state;
}

// In DevTools: Form: "Dirty, 2 errors"

Timer Hook#

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

function useTimer(initialTime: number) {
  const [time, setTime] = useState(initialTime);
  const [isRunning, setIsRunning] = useState(false);

  useEffect(() => {
    if (!isRunning) return;

    const interval = setInterval(() => {
      setTime((t) => Math.max(0, t - 1));
    }, 1000);

    return () => clearInterval(interval);
  }, [isRunning]);

  useDebugValue({ time, isRunning }, ({ time, isRunning }) => {
    const minutes = Math.floor(time / 60);
    const seconds = time % 60;
    const formatted = `${minutes}:${seconds.toString().padStart(2, '0')}`;
    return `${formatted} (${isRunning ? 'Running' : 'Paused'})`;
  });

  return { time, isRunning, start: () => setIsRunning(true), pause: () => setIsRunning(false) };
}

// In DevTools: Timer: "5:30 (Running)"

WebSocket Hook#

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

type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'error';

function useWebSocket(url: string) {
  const [state, setState] = useState<ConnectionState>('connecting');
  const [messageCount, setMessageCount] = useState(0);
  const wsRef = useRef<WebSocket | null>(null);

  useDebugValue({ state, messageCount }, ({ state, messageCount }) => {
    return `${state} (${messageCount} messages)`;
  });

  useEffect(() => {
    const ws = new WebSocket(url);
    wsRef.current = ws;

    ws.onopen = () => setState('connected');
    ws.onclose = () => setState('disconnected');
    ws.onerror = () => setState('error');
    ws.onmessage = () => setMessageCount((c) => c + 1);

    return () => ws.close();
  }, [url]);

  return { state, messageCount, ws: wsRef.current };
}

// In DevTools: WebSocket: "connected (42 messages)"

Media Query Hook#

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

function useMediaQuery(query: string) {
  const [matches, setMatches] = useState(() => {
    if (typeof window === 'undefined') return false;
    return window.matchMedia(query).matches;
  });

  useEffect(() => {
    const mediaQuery = window.matchMedia(query);
    const handler = (e: MediaQueryListEvent) => setMatches(e.matches);

    mediaQuery.addEventListener('change', handler);
    return () => mediaQuery.removeEventListener('change', handler);
  }, [query]);

  useDebugValue(`${query}: ${matches}`);

  return matches;
}

// In DevTools: MediaQuery: "(min-width: 768px): true"

Composed Hooks#

import { useDebugValue } from 'react';

function useUserPreferences(userId: string) {
  const { data: user } = useFetch<User>(`/api/users/${userId}`);
  const [theme] = useLocalStorage('theme', 'light');
  const [language] = useLocalStorage('language', 'en');
  const isOnline = useOnlineStatus();

  // Debug label for composed hook
  useDebugValue({
    user: user?.name,
    theme,
    language,
    isOnline,
  }, (state) => {
    return `${state.user || 'Loading'} | ${state.theme} | ${state.language} | ${state.isOnline ? '🟢' : '🔴'}`;
  });

  return { user, theme, language, isOnline };
}

// In DevTools: UserPreferences: "John | dark | en | 🟢"

Conditional Debug Value#

import { useDebugValue, useState } from 'react';

function useFeatureFlag(flagName: string) {
  const [enabled, setEnabled] = useState(false);
  const [loaded, setLoaded] = useState(false);

  // Only show debug value in development
  if (process.env.NODE_ENV === 'development') {
    // eslint-disable-next-line react-hooks/rules-of-hooks
    useDebugValue(
      { flagName, enabled, loaded },
      ({ flagName, enabled, loaded }) => {
        if (!loaded) return `${flagName}: loading...`;
        return `${flagName}: ${enabled ? '✓ enabled' : '✗ disabled'}`;
      }
    );
  }

  return { enabled, loaded };
}

Complex State Debugging#

import { useDebugValue, useReducer } from 'react';

interface State {
  items: Item[];
  selectedId: string | null;
  filter: string;
  sortBy: 'name' | 'date' | 'size';
  sortOrder: 'asc' | 'desc';
}

function useItemManager(initialItems: Item[]) {
  const [state, dispatch] = useReducer(reducer, {
    items: initialItems,
    selectedId: null,
    filter: '',
    sortBy: 'name',
    sortOrder: 'asc',
  });

  useDebugValue(state, (s) => {
    const filtered = s.filter ? `filtered "${s.filter}"` : 'unfiltered';
    const sorted = `sorted by ${s.sortBy} ${s.sortOrder}`;
    const selected = s.selectedId ? `selected: ${s.selectedId}` : 'none selected';
    return `${s.items.length} items, ${filtered}, ${sorted}, ${selected}`;
  });

  return { state, dispatch };
}

// In DevTools: ItemManager: "42 items, filtered "test", sorted by name asc, selected: item-123"

Best Practices#

When to Use:
✓ Custom hooks in libraries
✓ Complex hook state
✓ Debugging during development
✓ Team collaboration

Format Function:
✓ Use for expensive formatting
✓ Keep formatting simple
✓ Return readable strings
✓ Handle null/undefined

Content:
✓ Show relevant state
✓ Use concise labels
✓ Include counts/status
✓ Format dates/objects

Avoid:
✗ Using in every hook
✗ Complex computations
✗ Sensitive data
✗ Production overhead

useDebugValue enhances custom hooks with descriptive labels in React DevTools. Use the deferred formatting function for expensive operations to avoid performance impact. Focus on displaying the most relevant state information that helps during debugging. It's most valuable for reusable hooks in libraries or complex application hooks that benefit from clear state visibility.