useDebugValue 完全入門【React】カスタムフックをDevToolsでデバッグする

ReactのuseDebugValueとは何か、カスタムフックにDevTools用ラベルを追加する方法を解説。フォーマッタ関数を使ったパフォーマンス最適化の方法も紹介します。

#react#hooks#usedebugvalue#javascript#frontend

カスタムフックを作っていると、「React DevTools でこのフックの状態を確認したい」と思うことがあります。そんなときに使えるのが useDebugValue です。

このフックは開発ツール(DevTools)向けのラベルを追加するためのもので、アプリの動作には影響しません。使う場面は限られていますが、複雑なカスタムフックを作るときに役立ちます。

この記事でわかること:

  • useDebugValue の役割と使いどころ
  • 基本的な書き方
  • フォーマッタ関数を使ったパフォーマンス最適化
  • 使うべきシーンと使わなくていいシーン

useDebugValue とは?

useDebugValue は、カスタムフックに React DevTools 用のラベルを追加するフックです。

useDebugValue(value);
useDebugValue(value, formatFn); // フォーマッタ関数あり
パラメータ説明
valueDevTools に表示したい任意の値
formatFn(省略可能)value を受け取りフォーマット済みの値を返す関数

戻り値はありません(undefined)。

基本的な使い方

カスタムフックの中で呼び出すだけです。

import { useState, useEffect, useDebugValue } from "react";
 
function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(true);
 
  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);
    };
  }, []);
 
  // DevTools に "Online" または "Offline" と表示される
  useDebugValue(isOnline ? "Online" : "Offline");
 
  return isOnline;
}

React DevTools でこのフックを使っているコンポーネントを確認すると、フック名の横に "Online" または "Offline" と表示されます。

フォーマッタ関数で重い処理を遅延させる

DevTools が開いていないときはフォーマッタ関数の実行を避けたい場合があります。第2引数にフォーマッタ関数を渡すと、DevTools が値を表示するタイミングでのみフォーマットが実行されます。

import { useDebugValue } from "react";
 
function useLastActivity(userId) {
  const [lastActivity, setLastActivity] = useState(null);
 
  // ... データ取得ロジック ...
 
  // フォーマッタ関数:DevTools が表示するときだけ実行される
  useDebugValue(lastActivity, (date) => {
    if (!date) return "未アクティブ";
    return date.toLocaleString("ja-JP"); // 日本語形式でフォーマット
  });
 
  return lastActivity;
}

lastActivityDate オブジェクトの場合、DevTools には 2026/03/01 12:00:00 のような読みやすい形式で表示されます。

実用例:複数の値をまとめて表示

function useFormField(initialValue) {
  const [value, setValue] = useState(initialValue);
  const [isValid, setIsValid] = useState(true);
  const [isDirty, setIsDirty] = useState(false);
 
  // オブジェクトでまとめて渡すこともできる
  useDebugValue({ value, isValid, isDirty });
 
  const handleChange = (e) => {
    setValue(e.target.value);
    setIsDirty(true);
    setIsValid(e.target.value.length > 0);
  };
 
  return { value, isValid, isDirty, onChange: handleChange };
}

使うべき場面

✅ 使うべき場面
- 共有ライブラリとして公開するカスタムフック
- 状態が複雑で DevTools での確認が必要なカスタムフック
- チームで使う共通フックのデバッグ支援

❌ 不要な場面
- シンプルな値を返すだけのカスタムフック
- アプリ内でしか使わない小さなフック
- すべてのカスタムフック(追加しすぎに注意)

React の公式ドキュメントでも「すべてのカスタムフックにデバッグ値を追加しないでください」と明記されています。複雑なカスタムフックに絞って使いましょう。

本番環境への影響

useDebugValue本番環境(production build)では無視されます。パフォーマンスへの影響もありません。

開発中のデバッグを助けるためだけのフックなので、安心して使えます。

まとめ

  • useDebugValue はカスタムフックに React DevTools 用のラベルを追加するフック
  • アプリの動作には影響せず、本番環境では無視される
  • 第2引数にフォーマッタ関数を渡すと、DevTools 表示時のみ実行される
  • 複雑なカスタムフック・共有ライブラリ向けに使う
  • すべてのカスタムフックに追加する必要はない

PR

useDebugValue 公式ドキュメントで詳細を確認しよう

useDebugValueの詳細仕様や、カスタムフックのデバッグ方法は公式ドキュメントで確認できます。

useDebugValue 公式ドキュメントを見る

関連記事