React Hook Formで、ユーザー名の重複を入力中にチェックする方法
React Hook Form の register の validate に async 関数を渡し、useForm の mode を 'onChange' にすると、入力しているあいだにサーバーへ問い合わせてバリデーションできます。会員登録フォームで、ユーザー名がすでに使われているかを、送信する前に知らせたいときに使えます。そのままでは1文字打つごとに問い合わせが飛びますが、入力が止まってから1回だけ確かめる形(デバウンス)にすると、問い合わせは入力が止まるたびに1回で済みます。
私は、ユーザー名が使われているかを返す検証用の API を作り、入力のたびに問い合わせる形と、デバウンスを足した形を、検証環境で動かして比べました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、Chromium 153 です。使ったのは react / react-dom 19.3.1、react-hook-form 7.91.0、typescript 7.0.2、vite 8.3.8 です。tsc で型チェックしてから Vite の開発サーバーで動かし、Playwright で Chromium を操作しました。
問い合わせ先は本物のサーバーではなく、Vite の開発サーバーに足した検証用の API です。zod などの resolver の中で非同期に確かめる書き方、Controller を使う入力欄、react-hook-form v8(2026年11月11日の時点でベータ版)、ほかのブラウザは試していません。
検証用の API は、使われている名前だけ遅く返す
/api/username?name=〇〇 に問い合わせると、{ "available": true } か { "available": false } を返す API を、Vite の開発サーバーに足しました。admin・neko・tama の3つを「使われている名前」にしています。
応答の順番が入れ替わる場面を作るため、使われている名前だけ 1.5 秒、それ以外は 0.3 秒たってから返すようにしました。フォームからは、次の isUsernameAvailable で問い合わせます。
export async function isUsernameAvailable(name: string, signal?: AbortSignal): Promise<boolean> {
const res = await fetch(`/api/username?name=${encodeURIComponent(name)}`, { signal });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data: { available: boolean } = await res.json();
return data.available;
}
validate に async 関数を渡し、mode を onChange にする
まずは、いちばん素直な書き方です。validate の中で API に問い合わせ、使えるなら true、使えないならエラーの文を返します。
import { useState } from 'react';
import { useForm } from 'react-hook-form';
import { isUsernameAvailable } from './api';
type FormValues = { username: string };
export function PlainForm() {
const [sent, setSent] = useState<FormValues | null>(null);
const {
register,
handleSubmit,
formState: { errors, validatingFields, isSubmitting },
} = useForm<FormValues>({ mode: 'onChange', defaultValues: { username: '' } });
return (
<form onSubmit={handleSubmit((data) => setSent(data))} noValidate>
<label>
ユーザー名
<input
{...register('username', {
required: 'ユーザー名を入力してください',
minLength: { value: 3, message: '3文字以上にしてください' },
validate: async (value) =>
(await isUsernameAvailable(value)) || 'このユーザー名はすでに使われています',
})}
/>
</label>
{validatingFields.username && <p className="checking">確認中…</p>}
{errors.username && <p className="error">{errors.username.message}</p>}
<button type="submit" disabled={isSubmitting}>登録</button>
{sent && <pre>{JSON.stringify(sent)}</pre>}
</form>
);
}
公式リファレンスの register のページによると、validate の関数が true か undefined を返せば正しい値、文字列を返せばその文がエラーのメッセージになります。同じページには、async 関数で在庫を問い合わせる例も載っています。
useForm の mode は、既定では 'onSubmit' で、送信するまでバリデーションしません(公式リファレンスの mode の説明)。入力のたびに確かめるには 'onChange' にします。
問い合わせている最中かどうかは、formState.validatingFields で分かります。公式リファレンスの formState のページにあるとおり、非同期のバリデーションをしている入力欄の名前が入ります。上のコードでは、validatingFields.username が true のあいだ「確認中…」を出しています。
3文字未満のあいだは、問い合わせが飛ばない
検証環境で「ab」と打って1秒待っても、API への問い合わせは0回でした。画面には「3文字以上にしてください」だけが出ました。
react-hook-form 7.91.0 のソースを読むと、1つの入力欄のルールは required、min・max、minLength・maxLength、pattern の順に調べ、validate はその後に呼ぶ作りでした。既定の設定(公式リファレンスの criteriaMode の説明によると firstError)では、手前のルールでエラーが見つかった時点で調べるのをやめます。そのため、文字数のような手元で分かるルールを register に並べておくと、サーバーへの問い合わせを減らせます。
1文字ごとに問い合わせると、表示が前の結果に引きずられる
PlainForm で「tama1234」を0.1秒おきに1文字ずつ入れると、API への問い合わせは6回飛びました。3文字目の「tam」から、1文字ごとに1回ずつです。
古い問い合わせの結果が、新しい入力の結果を上書きすることはありませんでした。「tama」(使われている名前なので1.5秒かかる)と打った0.1秒後に「1」を足すと、「tama1」の結果(0.3秒)が先に届き、その約1.1秒後に「tama」の結果が届きました。それでも画面には「すでに使われています」は出ませんでした。react-hook-form は、validate の結果を使う前に、入力欄の値が確かめ始めたときと同じかを比べ、違えば結果を捨てています。
一方で、画面の表示には気になる動きが2つありました。
1つ目は、前のエラーが残ることです。「tam」と打った直後は、「確認中…」と並んで、2文字のときの「3文字以上にしてください」が出たままでした。前のエラーは、validate が終わるまで消えません。
2つ目は、「確認中…」が早く消えることです。「tam」と打った0.05秒後に「a」を足すと、0.3秒後に「tam」の結果が届いた時点で「確認中…」が消えました。「tama」の結果が届いたのはその1.2秒後で、そのあいだ画面には「3文字以上にしてください」だけが出ていました。validatingFields は入力欄ごとに true を入れるか消すかだけで、問い合わせが何件残っているかは数えません。そのため、捨てられる古い結果が届いたときにも、確認中ではない状態に戻ります。
入力が止まってから1回だけ確かめるフックを作る
問い合わせの回数を減らし、表示も落ち着かせるため、入力が止まって0.5秒たってから1回だけ確かめる useDebouncedValidate を作りました。
import { useCallback, useRef } from 'react';
import type { ValidateResult } from 'react-hook-form';
type Check = (value: string, signal: AbortSignal) => Promise<ValidateResult>;
// 最後の呼び出しから delay ミリ秒たったら1回だけ確かめ、
// 待っているすべての呼び出しに、その結果を返す
export function useDebouncedValidate(check: Check, delay: number) {
const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
const controller = useRef<AbortController | null>(null);
const waiting = useRef<((result: ValidateResult) => void)[]>([]);
return useCallback(
async (value: string) =>
new Promise<ValidateResult>((resolve) => {
waiting.current.push(resolve);
clearTimeout(timer.current);
controller.current?.abort();
timer.current = setTimeout(async () => {
const c = new AbortController();
controller.current = c;
let result: ValidateResult;
try {
result = await check(value, c.signal);
} catch {
// 新しい入力で取り消したときは、次の結果を待つ
if (c.signal.aborted) return;
result = '確認できませんでした。時間をおいて試してください';
}
const resolvers = waiting.current;
waiting.current = [];
resolvers.forEach((r) => r(result));
}, delay);
}),
[check, delay],
);
}
react-hook-form は入力のたびに validate を呼びます。このフックが返す関数は、呼ばれるたびに前の待ち時間(setTimeout)を取り消して、0.5秒の待ちをやり直します。問い合わせの途中で新しい入力が来たときは、AbortController の abort() で通信を取り消します。MDN の abort() のページにあるとおり、取り消された fetch() は AbortError で失敗し、catch に入ります。そこで c.signal.aborted を見て、取り消しかどうかを見分けています。
検証用の API が 500 を返すようにして試すと、isUsernameAvailable が投げたエラーを catch で受け取り、「確認できませんでした。時間をおいて試してください」が出ました。
フォームの側では、validate にこのフックが返した関数を渡します。
import { useState } from 'react';
import { useForm } from 'react-hook-form';
import { isUsernameAvailable } from './api';
import { useDebouncedValidate } from './useDebouncedValidate';
type FormValues = { username: string };
const checkUsername = async (value: string, signal: AbortSignal) =>
(await isUsernameAvailable(value, signal)) || 'このユーザー名はすでに使われています';
export function DebouncedForm() {
const [sent, setSent] = useState<FormValues | null>(null);
const validateUsername = useDebouncedValidate(checkUsername, 500);
const {
register,
handleSubmit,
formState: { errors, validatingFields, dirtyFields, isSubmitting },
} = useForm<FormValues>({ mode: 'onChange', defaultValues: { username: '' } });
return (
<form onSubmit={handleSubmit((data) => setSent(data))} noValidate>
<label>
ユーザー名
<input
{...register('username', {
required: 'ユーザー名を入力してください',
minLength: { value: 3, message: '3文字以上にしてください' },
validate: validateUsername,
})}
/>
</label>
{validatingFields.username && <p className="checking">確認中…</p>}
{!validatingFields.username && errors.username && <p className="error">{errors.username.message}</p>}
{dirtyFields.username && !validatingFields.username && !errors.username && <p className="ok">使えます</p>}
<button type="submit" disabled={isSubmitting}>登録</button>
{sent && <pre>{JSON.stringify(sent)}</pre>}
</form>
);
}
前のエラーが残る問題には、確認中はエラーを出さないことで対応しました(!validatingFields.username && errors.username)。「使えます」は、入力欄を一度でも書き換えていて(dirtyFields.username)、確認中でもエラーでもないときに出します。
このフォームで「tama1234」を0.1秒おきに入れると、問い合わせは最後の「tama1234」の1回だけでした。最後の文字を入れてから約0.5秒後です。そのあいだ画面には「確認中…」だけが出て、結果が届くと「使えます」に変わりました。
次の GIF は、「tama」と打って待ち、「すでに使われています」が出たあとに「1」を足したところです。上の帯の右に、API に問い合わせた回数を出しています。

「tama」の問い合わせが終わる前(打ち終えてから1秒後)に「1」を足した場合も試しました。「tama」への通信は取り消され(Chromium では net::ERR_ABORTED)、その0.5秒後に「tama1」を問い合わせて「使えます」が出ました。
待っているすべての呼び出しに結果を返す理由
最初は、取り消した呼び出しの Promise を解決しないまま置いておく形で作りました。入力中の動きは同じでしたが、「mike」と打ってすぐ「登録」を押すと、送信は成功したのに「確認中…」が消えませんでした(押してから1.5秒待って確かめました)。
「登録」を押すと、handleSubmit が送信の前にもう一度 validate を呼びます。このとき、入力で呼ばれた validate の待ちが、送信時の呼び出しで取り消されます。react-hook-form 7.91.0 のソースでは、入力のときの処理は validate の Promise が解決するのを待ってから validatingFields を false に戻します。取り消された側の Promise は解決されないので、validatingFields.username が true のまま残りました。
そこで、待っている呼び出しを waiting に並べておき、最後の問い合わせの結果を全員に返す形に直しました。直したあとは、「mike」と打ってすぐ「登録」を押すと、問い合わせは1回だけで、約0.9秒後に「使えます」と送信したデータが出ました。「tama」で同じことをすると「すでに使われています」が出て、送信の処理は呼ばれませんでした。
返す関数に async を付けると、送信中も「確認中…」が出る
上のフックでは、new Promise を返すだけの関数に、わざわざ async を付けています。これを外すと、送信のときの表示が変わりました。
「mike」と打って「使えます」が出てから「登録」を押すと、async を付けた関数では、送信の処理が終わるまでの約0.8秒「確認中…」が出ました。async を外した関数では、そのあいだも「使えます」のままでした。どちらも、そのあいだ「登録」ボタンは押せない状態(isSubmitting が true)で、送信そのものは成功しました。
react-hook-form 7.91.0 のソースでは、送信時に validatingFields.username を true にするのは、validate の関数の constructor.name が AsyncFunction のときだけでした。Promise を返していても、async で書かれた関数でなければ、送信時の確認中の表示は出ません。入力中の確認では、どちらでも validatingFields.username が true になり、「確認中…」が出ました。





