【React】useRefの使い方!DOM操作と値の保持を完全解説

【React】useRefの使い方!DOM操作と値の保持を完全解説

PR Amazonのアソシエイトとして、ITナレッジライフは適格販売により収入を得ています。

記事の文字数:5,249

ReactのuseRefフックの使い方をわかりやすく解説。DOM要素へのアクセス(フォーカス・スクロール制御)や、再レンダリングを起こさずに値を保持するミュータブル変数の活用法、TypeScriptでの型定義、useStateとの違い、アンチパターンとテスト手法まで網羅します。

ITエンジニアにお勧めの本 ↗

おすすめ

エンジニアが知っておきたい思考の整理術 複雑な情報を【理解する】【伝える】テクニック

難易度
実用性
図解

思考の整理というテーマを、実務ですぐに使える具体的な「技術」として落とし込んだ一冊です。

ベストセラー

世界一流エンジニアの思考法

難易度
実用性
思考法

技術スキル以上に大切な「考え方」をアップデートできる。世界基準の効率的な仕事術が学べます。

文系社会人のためのIT資格の歩き方: 文系のあなたに最適な道をご提案します (YKcreate kiki)

難易度
実用性
キャリア度

ロードマップが非常に明確。キャリアプランを見据えた、無駄のない学習順序を提案してくれます。

エンジニアを説明上手にする本 相手に応じた技術情報や知識の伝え方

難易度
実用性
コミュ力

「伝える技術」もエンジニアの重要なスキル。相手の視点に立った、具体的な説明のコツが満載です。

技術広報入門 ー テックブログから始めるエンジニアカルチャーのつくり方

難易度
実用性
独自性

テックブログを入口にエンジニア組織の文化をどう設計し、育てていくかという実践論が学べます。

ReactReact [リアクト]Meta開発のUIライブラリでコンポーネントを開発していると、「画面を再レンダリングせずに前回の値やタイマーIDを保持したい」「ボタンをクリックしたときに特定の入力フォームへ自動でフォーカスを当てたい」といった要件に遭遇することがあります。

Reactの基本である useState は、状態を更新するたびにコンポーネントを再レンダリングします。そのため、描画に関係のない内部データの保持に useState を使うと、不要な再描画が発生してパフォーマンス低下の原因になります。また、Reactの宣言型UIUI [ユーアイ]User Interface。ユーザーとシステムの間で情報をやり取りする接点や画面モデルでは、通常はDOMDOM [ドム]Document Object Model。HTMLの木構造の表現を直接操作しませんが、フォーカス制御やスクロール位置の取得など、命令的なDOMアクセスが避けられない場面も存在します。

これらの課題を解決するフックが useRef です。

本記事では、useRef の基本概念や2大用途(DOM参照と値の保持)、TypeScriptTypeScript [タイプスクリプト]JavaScriptに型システムを追加した言語での厳格な型定義とエラーハンドリング、useState との使い分け基準、避けるべきアンチパターン、Vitestを用いたテスト手法までを体系的に解説します。

推奨・確認環境

本記事で解説するコード例やベストプラクティスは、以下の環境での動作を想定しています。

項目推奨・検証バージョン補足
Node.jsv22.x / v24.x現行LTS対象環境
React18.3 / 19.x関数コンポーネント環境(Hooks)
TypeScript5.xstrict: true(厳格モード)推奨
Vitest2.x以上単体・結合テストフレームワーク
Testing Library16.x(@testing-library/react)Reactコンポーネントのテスト用

React 18の Strict Mode や React 19 環境でも安心して動作する書き方で解説します。

スポンサーリンク

useRefとは?仕組みとuseStateとの違い

useRef は、 「再レンダリングを引き起こさずに値を保持できるコンテナ(Refオブジェクト)」 を返すReact標準のフックです。

useRefの内部構造

useRef を呼び出すと、次のような単一のプロパティを持つプレーンなJavaScriptオブジェクトが返されます。

const ref = useRef(initialValue);
// 返されるオブジェクトの実体: { current: initialValue }

この { current: initialValue } というオブジェクトは、コンポーネントのマウントからアンマウントまでのライフサイクル全体を通じて、 同一の参照が保持 されます。

通常のコンポーネント内ローカル変数はレンダリングごとに初期化されますが、ref.current に代入した値は再レンダリングを跨いでも消失しません。さらに、ref.current の値を書き換えても、 コンポーネントの再レンダリングは発生しません 。

useStateとuseRefの比較

どちらも「コンポーネント内で値を保持する」機能ですが、目的と挙動が明確に異なります。

比較項目useStateuseRef
返り値現在の状態値と更新関数 [state, setState]{ current: value } オブジェクト
値の変更方法setState(newValue) を実行ref.current = newValue に直接代入
値変更時の挙動コンポーネントが 再レンダリングされる再レンダリングされない
主な用途画面表示・UIに反映されるデータDOM参照、タイマーID、前回の状態、フラグ管理
レンダリング中の読み取り可能(JSX内で直接参照)原則禁止(イベントハンドラーや副作用内で使用)

画面上に表示する値であれば useState を選び、画面表示には直接影響しない「裏側のメタデータ」や「DOMへの命令的アクセス」には useRef を選ぶのが基本原則です。

useRefの2大用途と最小動作コード

useRef には大きく分けて2つの使い道があります。それぞれの最小動作コードを確認しましょう。

用途1: DOM要素への命令的アクセス(フォーカス制御)

最も代表的な用途が、HTMLHTML [エイチティーエムエル]HyperText Markup Language。Webページの構造を記述する言語のDOM要素への参照を取得し、命令的な操作を行うパターンです。

以下の例は、ボタンをクリックした際に入力フォーム(<input>)へフォーカスを移動する最小コードです。

import React, { useRef } from "react";
export const TextInputWithFocus: React.FC = () => {
// 1. 初期値 null で Ref オブジェクトを作成
const inputRef = useRef<HTMLInputElement>(null);
const handleFocusClick = () => {
// 3. current プロパティ経由で DOM メソッドを実行
if (inputRef.current) {
inputRef.current.focus();
}
};
return (
<div style={{ padding: "16px" }}>
{/* 2. JSXの ref 属性に対象の Ref を渡す */}
<input
ref={inputRef}
type="text"
placeholder="ここに入力してください"
/>
<button onClick={handleFocusClick} style={{ marginLeft: "8px" }}>
フォーカスを当てる
</button>
</div>
);
};

動作の流れ

  1. useRef<HTMLInputElement>(null) で Ref オブジェクトを初期化します。
  2. JSXで <input ref={inputRef} /> のように渡すと、ReactがDOMノードを生成したタイミングで inputRef.current に実際のDOM要素への参照を格納します。
  3. イベントハンドラー内で inputRef.current.focus() を呼び出すことで、DOM APIAPI [エーピーアイ]Application Programming Interface。異なるソフトウェア間の接続口を安全に実行できます。

用途2: 再レンダリングを起こさない値の保持(タイマー管理)

もう1つの重要な用途が、コンポーネントの内部変数としての利用です。

例えば setInterval や setTimeout のタイマーIDを保持する場合、タイマーIDが変わっても画面のUIを再描画する必要はありません。このような値は useRef で管理するのが最適です。

import React, { useState, useRef, useEffect } from "react";
export const StopWatch: React.FC = () => {
const [seconds, setSeconds] = useState<number>(0);
const [isRunning, setIsRunning] = useState<boolean>(false);
// NodeJS.Timeout または number 型のタイマーIDを保持
const timerIdRef = useRef<ReturnType<typeof setInterval> | null>(null);
const startTimer = () => {
if (timerIdRef.current !== null) return;
setIsRunning(true);
timerIdRef.current = setInterval(() => {
setSeconds((prev) => prev + 1);
}, 1000);
};
const stopTimer = () => {
if (timerIdRef.current !== null) {
clearInterval(timerIdRef.current);
timerIdRef.current = null;
setIsRunning(false);
}
};
// コンポーネントがアンマウントされたときのクリーンアップ
useEffect(() => {
return () => {
if (timerIdRef.current !== null) {
clearInterval(timerIdRef.current);
}
};
}, []);
return (
<div>
<p>経過時間: {seconds} 秒</p>
<button onClick={startTimer} disabled={isRunning}>
スタート
</button>
<button onClick={stopTimer} disabled={!isRunning} style={{ marginLeft: "8px" }}>
ストップ
</button>
</div>
);
};

もし timerIdRef を useState で管理してしまうと、タイマーIDの更新によって不要な再レンダリングが発生してしまいます。useRef を使えば、タイマーIDの更新による再レンダリングは発生しません。

スポンサーリンク

TypeScriptでの型定義と安全なエラーハンドリング

TypeScriptで useRef を扱う際、引数の渡し方によって推論される型定義が異なる点に注意が必要です。

RefObject vs MutableRefObject

useRef の戻り値の型は、Reactの型定義(@types/react)のメジャーバージョンによって異なります。

React 18(@types/react 18.x)の場合 は、次の3種類のオーバーロードが存在します。

// 1. DOM参照用(初期値 null 指定): RefObject<T>
// ref.current は「読み取り専用(readonly)」として扱われる
const inputRef = useRef<HTMLInputElement>(null);
// 2. ミュータブルな値保持用: MutableRefObject<T>
// ref.current は「読み書き自由」
const counterRef = useRef<number>(0);
// 3. 初期値未指定(非推奨): MutableRefObject<T | undefined>
const looseRef = useRef<number>();

React 19(@types/react 19.x)の場合 は型定義が整理され、戻り値はすべて RefObject<T> に統一されました。current は読み書き可能になり、MutableRefObject は非推奨(deprecateddeprecated [デプリケーテッド]非推奨。将来削除される予定の機能)です。また、引数が必須になったため、初期値を省略した useRef<number>() は「Expected 1 arguments, but got 0.」という型エラーになります。

// React 19 の型定義
const inputRef = useRef<HTMLInputElement>(null); // RefObject<HTMLInputElement | null>
const counterRef = useRef<number>(0); // RefObject<number>
const looseRef = useRef<number | undefined>(undefined); // 初期値は明示が必須

どちらのバージョンでも、DOM要素の参照を目的とする場合は 初期値に null を指定 してください(useRef<HTMLInputElement>(null))。JSXの ref 属性に渡すオブジェクトとして正しく適合します。React 18 の型定義では current が readonly 扱いとなるため、意図しない手動での書き換えも防げます。

オプショナルチェイニングとnullガード

マウント前の初期レンダリング時や、条件分岐によってコンポーネントがアンマウントされている間は、ref.current の値は null になります。

そのため、プロパティやメソッドにアクセスする際は、必ず nullnull [ヌル / ナル]値が存在しないことを表す特殊な値ガード または オプショナルチェイニング(?.) を適用します。

// パターンA: オプショナルチェイニングによる安全な呼び出し
inputRef.current?.focus();
// パターンB: 明示的な null ガードによる安全なブロック実行
if (inputRef.current !== null) {
inputRef.current.select();
const rect = inputRef.current.getBoundingClientRect();
console.log("要素の幅:", rect.width);
}

TypeScriptの型安全性を活かすことで、本番環境での TypeError: Cannot read properties of null を未然に防止できます。

アンチパターン vs ベストプラクティス

useRef の手軽さから、間違った使い方をしてReactの設計思想を壊してしまうケースが散見されます。代表的なアンチパターンとベストプラクティスを比較します。

1. レンダリング中の ref.current 読み書き

Reactのコンポーネント関数本体(JSXを返すレンダリングパス)は、純粋関数として動作する必要があります。レンダリング中に副作用を起こす処理や、外部ミュータブル変数の読み書きを行ってはいけません。

// ❌ アンチパターン: レンダリング中に ref.current を変更する
const BadCounter: React.FC = () => {
const renderCountRef = useRef<number>(0);
// レンダリング中に直接インクリメント(副作用)
renderCountRef.current++;
return <div>レンダリング回数: {renderCountRef.current}</div>;
};
// ⭕ ベストプラクティス: useEffect またはイベントハンドラーで更新する
const GoodCounter: React.FC = () => {
const renderCountRef = useRef<number>(0);
useEffect(() => {
// マウントまたはレンダリング完了後の副作用として記録
renderCountRef.current++;
});
return <div>コンポーネント描画完了</div>;
};

React 18 以降の並行レンダリング(Concurrent Rendering)では、レンダリング処理が中断・再実行される可能性があります。また、開発時の Strict Mode ではコンポーネント関数が意図的に2回呼び出されます。レンダリング中に ref.current を変更すると、こうした再実行によって値の整合性が崩れる原因になります。

2. 画面に反映すべき状態を useRef で管理する

「再レンダリングを抑えたいから」という理由で、画面に表示すべき値まで useRef で管理してしまうケースです。

// ❌ アンチパターン: ref.current を更新しても画面は更新されない
const BrokenDisplay: React.FC = () => {
const countRef = useRef<number>(0);
const handleClick = () => {
countRef.current += 1;
// countRef は増えるが、再レンダリングされないため画面の数字は 0 のまま!
};
return (
<div>
<p>カウント: {countRef.current}</p>
<button onClick={handleClick}>+1</button>
</div>
);
};

画面に表示する値は、素直に useState を使用してください。パフォーマンスの懸念がある場合は、コンポーネントの分割や Reactカスタムフックの作り方 を検討します。

【React】カスタムフック(Custom Hook)の作り方!基礎から解説
ITナレッジライフ

【React】カスタムフック(Custom Hook)の作り方!基礎から解説

Reactのカスタムフック(Custom Hooks)の作り方を徹底解説。基本ルールや命名規約、最小コード例からTypeScriptでの型定義、API通信やイベント監視の実装例、テスト手法、アンチパターンと回避策まで実務で役立つ知識を体系的に紹介します。

3. Reactが管理するDOMを直接書き換える

ref.current を取得したからといって、innerHTML や appendChild、removeChild などのDOM直接変更を行うと、Reactの仮想DOMツリーとの整合性が破綻し、予期せぬバグを引き起こします。

// ❌ アンチパターン: DOMを直接変更する
if (divRef.current) {
divRef.current.innerHTML = "<span>直接書き換えたHTML</span>";
}
// ⭕ ベストプラクティス: Reactの宣言的StateでUIを更新する
const [content, setContent] = useState<string>("初期メッセージ");

useRef によるDOM操作は、フォーカスの制御、スクロール位置の調整(scrollIntoView)、要素寸法の計測(getBoundingClientRect)など、 Reactの宣言的な機能では代替できない命令的処理のみに限定 しましょう。

スポンサーリンク

VitestとTesting Libraryでのテスト手法

useRef を用いたコンポーネントの単体テストは、Vitest と @testing-library/react を組み合わせて実施します。

テストの基本原則として、コンポーネント内部の ref.current というプライベートな状態を直接覗き見るのではなく、 「ユーザー操作によって期待される振る舞い(フォーカスが当たったか等)」を検証 します。

なお、toHaveFocus() はVitest標準のマッチャーではなく @testing-library/jest-dom が提供するカスタムマッチャーです。事前に関連パッケージをインストールし、DOM環境(jsdom)とセットアップファイルを設定しておく必要があります。

Terminal window
npm install -D vitest jsdom @testing-library/react @testing-library/dom @testing-library/user-event @testing-library/jest-dom
vitest.config.ts
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
environment: "jsdom",
setupFiles: ["./vitest.setup.ts"],
},
});
vitest.setup.ts
import "@testing-library/jest-dom/vitest";

この設定がない場合、テスト実行時に「Invalid Chai property: toHaveFocus」というエラーで失敗します。

TextInputWithFocus.test.tsx
import { describe, it, expect } from "vitest";
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import React from "react";
import { TextInputWithFocus } from "./TextInputWithFocus";
describe("TextInputWithFocus コンポーネントの検証", () => {
it("ボタンをクリックすると入力欄にフォーカスが当たる", async () => {
const user = userEvent.setup();
render(<TextInputWithFocus />);
const input = screen.getByPlaceholderText("ここに入力してください");
const button = screen.getByRole("button", { name: "フォーカスを当てる" });
// 初期状態ではフォーカスが当たっていないことを確認
expect(input).not.toHaveFocus();
// ボタンをクリック
await user.click(button);
// input要素にフォーカスが移動していることを検証
expect(input).toHaveFocus();
});
});

このテストコードにより、DOMの参照取得と命令的メソッドの呼び出しが実環境で正常に連携していることを自動検証できます。

テスト手法の基礎や Vitest の導入手順については、以下の 【Vitest】基本的な使い方入門 でも詳しく解説しています。

【Vitest】基本的な使い方入門!Jestとの違いやテストの書き方を解説
ITナレッジライフ

【Vitest】基本的な使い方入門!Jestとの違いやテストの書き方を解説

Vitestの基本的な使い方を初心者向けに徹底解説!Vite環境に最適化された高速なユニットテストフレームワークの導入手順から、テストコードの書き方、Jestとの違いやviモックの活用法まで、実機検証の出力結果を交えてわかりやすく紹介します。

前回の値を保持するカスタムフック(usePrevious)

実務で非常によく使われる useRef の応用パターンとして、「直前のレンダリング時のPropsやStateの値を保持するカスタムフック」があります。

import { useEffect, useRef } from "react";
/**
* 直前のレンダリング時の値を保持して返すカスタムフック
*/
export function usePrevious<T>(value: T): T | undefined {
const ref = useRef<T | undefined>(undefined);
useEffect(() => {
// レンダリングが完了した後に最新の値を保持する
ref.current = value;
}, [value]);
// レンダリング中は「前回の値」が返される
return ref.current;
}

使用例:Stateの変動を検知する

import React, { useState } from "react";
import { usePrevious } from "./usePrevious";
export const PriceTracker: React.FC = () => {
const [price, setPrice] = useState<number>(1000);
const prevPrice = usePrevious(price);
return (
<div>
<p>現在価格: {price} 円</p>
<p>前回価格: {prevPrice !== undefined ? `${prevPrice} 円` : "(初回)"}</p>
<button onClick={() => setPrice((p) => p + 100)}>値上げ</button>
<button onClick={() => setPrice((p) => p - 100)} style={{ marginLeft: "8px" }}>
値下げ
</button>
</div>
);
};

useEffect の実行タイミング(レンダリング後・画面コミット後)を利用することで、「コンポーネントのレンダリング中には前回の値を返し、画面反映後に新しい値へと更新する」という連携が実現できます。

ただし、この usePrevious はレンダリング中に ref.current を読み取るため、前述の「レンダリング中の読み取りは原則禁止」の例外にあたります。また、value 以外の理由で再レンダリングされた場合は「前回価格」が現在の値と同じになります。React公式ドキュメントでは、前回の値を useState で保持してレンダリング中に比較・更新するパターンも紹介されているため、厳密さが求められる場面ではそちらも検討してください。

他の標準フックとの連携やコンテキスト共有については、以下の 【React】useContextの使い方 も合わせてご覧ください。

【React】useContextの使い方!基本から実践パターンまで徹底解説
ITナレッジライフ

【React】useContextの使い方!基本から実践パターンまで徹底解説

ReactのuseContextフックの使い方をわかりやすく解説。createContextによるコンテキスト作成からProviderの設定、TypeScriptでの型安全なカスタムフック化パターン、不要な再レンダリングを防ぐベストプラクティス、境界テストまで網羅します。

まとめ

本記事では、Reactの重要フックである useRef の役割、2大用途、TypeScriptでの型安全性、アンチパターン、テスト手法について解説しました。

最後に要点を整理します。

項目ポイント
本質再レンダリングを起こさずに、コンポーネントの全期間で同一の参照 { current: value } を保持する
用途1: DOM参照useRef<T>(null) で要素を取得。フォーカス・スクロール・計測などの命令的処理に限定する
用途2: 値の保持タイマーIDや前回の値など、画面描画に影響しないメタデータを安全に管理する
TypeScriptの型React 18 はDOM参照が RefObject<T>(初期値null)、値保持が MutableRefObject<T>。React 19 は RefObject<T> に統一され引数必須
アンチパターンレンダリング中の current 変更、画面反映ステートの代替、React管理DOMの直接書き換え
テスト方針ref.current の内部値を直接覗かず、DOMのフォーカス状態や振る舞いを検証する

useRef はシンプルながら、Reactの宣言的UIとブラウザの命令的APIを繋ぐ架け橋となる重要な機能です。適切な使い分けを理解して、堅牢でパフォーマンスの高いReactアプリケーションを構築しましょう。


以上で本記事の解説を終わります。
よいITライフを!
スポンサーリンク
ITナレッジライフ 運営者
この記事を書いた人

Z (ITナレッジライフ)

現役のITエンジニア。Linux、プログラミング、IT用語など、日々の業務で得た「痒いところに手が届く」技術情報を発信しています。

プロフィールと編集ポリシーを見る →
スポンサーリンク

ITエンジニアにお勧めの本 ↗

おすすめ

エンジニアが知っておきたい思考の整理術 複雑な情報を【理解する】【伝える】テクニック

難易度
実用性
図解

思考の整理というテーマを、実務ですぐに使える具体的な「技術」として落とし込んだ一冊です。

スポンサーリンク

人気記事


記事を評価

Thanks!
目次
Scroll to Top