ReactとTanStack Formで会員登録フォームを作る方法
TanStack Form を使うと、React のフォームの値・入力チェック・送信中の状態を useForm 1つで持てます。入力欄は form.Field の中に書き、入力チェック(バリデーション)は欄ごとに「入力のたび」か「フォーカスが外れたとき」かを選んで付けます。会員登録フォームでよくある「メールアドレス」「パスワード」「パスワード(確認)」の3つの欄を作り、確認欄の値がパスワードと一致しないときにエラーを出すところまで、検証環境で動かしました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、Chromium 153 です。使ったのは @tanstack/react-form 1.33.5、react / react-dom 19.3.1、typescript 7.0.2、vite 8.3.8 です。tsc で型チェックしてから Vite の開発サーバーで動かし、Playwright で Chromium を操作しました。
公式ドキュメントの Quick Start がすすめる createFormHook(入力欄の部品を登録して使う書き方)、Zod などのスキーマを使った入力チェック、サーバーに問い合わせる非同期の入力チェック、送信ボタンの aria-disabled、ほかのブラウザは試していません。送信先も本物のサーバーではなく、1秒待つだけの関数です。
useForm でフォームを作り、送信は handleSubmit に任せる
まず、パッケージを入れます。
npm install @tanstack/react-form
フォームは useForm で作ります。defaultValues に初めの値を、onSubmit に送信の処理を渡します。defaultValues に型を付けておくと、フォームの値の型がそこから決まります。
import { useState } from 'react';
import { useForm } from '@tanstack/react-form';
import { FieldError } from './FieldError';
type SignupValues = {
email: string;
password: string;
confirmPassword: string;
};
const defaultValues: SignupValues = { email: '', password: '', confirmPassword: '' };
export function SignupForm() {
const [sent, setSent] = useState<SignupValues | null>(null);
const form = useForm({
defaultValues,
onSubmit: async ({ value }) => {
// 本物のアプリでは、ここでサーバーに送る
await new Promise((r) => setTimeout(r, 1000));
setSent(value);
form.reset();
},
});
return (
<form
noValidate
onSubmit={(e) => {
e.preventDefault();
form.handleSubmit();
}}
>
{/* ここに form.Field を並べる(次の節) */}
{sent && <pre>{JSON.stringify(sent)}</pre>}
</form>
);
}
<form> の onSubmit では、ブラウザの送信(ページの再読み込み)を e.preventDefault() で止めてから、form.handleSubmit() を呼びます。公式ドキュメントの Quick Start も同じ形です。handleSubmit は入力チェックをすべてやり直し、通ったときだけ onSubmit を呼びます。
送信が終わったら form.reset() で defaultValues に戻しています。検証環境では、送信のあと3つの欄が空に戻り、送った値が画面に出ました。
入力欄は form.Field の children に書く
1つの入力欄は form.Field で作ります。name に defaultValues のキーを書き、children に関数を渡すと、その欄の値やエラーを持つ field を受け取れます(公式ドキュメントの Basic Concepts のページ)。
<form.Field
name="email"
validators={{
onBlur: ({ value }) =>
!value
? 'メールアドレスを入力してください'
: !/^[^@\s]+@[^@\s]+$/.test(value)
? 'メールアドレスの形式が正しくありません'
: undefined,
}}
>
{(field) => (
<label>
メールアドレス
<input
type="email"
name={field.name}
value={field.state.value}
onBlur={field.handleBlur}
onChange={(e) => field.handleChange(e.target.value)}
/>
<FieldError field={field} />
</label>
)}
</form.Field>
value に field.state.value を、onChange に field.handleChange を、onBlur に field.handleBlur をつなぎます。公式ドキュメントの例でも、フォーカスが外れたときに入力チェックをする欄では、onBlur に field.handleBlur を渡しています。
name は型で守られます。defaultValues が { email: '', age: 0 } のフォームで name="emial" と打ち間違えると、tsc は次のエラーを出しました。数値の欄(age)の handleChange に文字列を渡したときもエラーになりました。
error TS2820: Type '"emial"' is not assignable to type '"age" | "email"'. Did you mean '"email"'?
error TS2345: Argument of type 'string' is not assignable to parameter of type 'Updater<number>'.
エラーメッセージは、次の FieldError で出しています。isTouched は、欄の値を変えるかフォーカスを外すと true になります。FieldError で isTouched を見ているのは、まだ触っていない欄にエラーを出さないためです。
import type { AnyFieldApi } from '@tanstack/react-form';
export function FieldError({ field }: { field: AnyFieldApi }) {
const { isTouched, isValid, errors } = field.state.meta;
if (!isTouched || isValid) return null;
return <p className="error" role="alert">{errors.join('、')}</p>;
}
エラーを出すタイミングは、validators のキーで選ぶ
入力チェックは validators に関数で書きます。エラーがあれば文字列を返し、なければ undefined を返します。キーを onChange にすると入力のたびに、onBlur にするとフォーカスが外れたときに動きます(公式ドキュメントの入力チェックのページ)。
メールアドレスは、打っている途中で「形式が正しくありません」と出ると邪魔なので onBlur にしました。パスワードは、8文字に届いたかをすぐ知らせたいので onChange にしています。
<form.Field
name="password"
validators={{
onChange: ({ value }) =>
value.length < 8 ? '8文字以上にしてください' : undefined,
}}
>
{/* 入力欄はメールアドレスと同じ形(type="password") */}
</form.Field>
検証環境での動きは次のとおりでした。
- メールアドレスに「neko」と打っているあいだはエラーが出ず、フォーカスを外すと「メールアドレスの形式が正しくありません」が出ました。
- そのまま「neko@example.com」まで打っても、エラーはフォーカスを外すまで残りました。
onBlurの入力チェックは、次にフォーカスが外れるまでやり直されません。 - パスワードは「abc」と打った時点で「8文字以上にしてください」が出て、8文字目で消えました。
- 何も入れずに「登録する」を押すと、メールアドレスとパスワードの両方にエラーが出ました。送信のときは
onBlurの入力チェックも動き、すべての欄のisTouchedがtrueになるためです。
パスワードを変えたら、onChangeListenTo で確認欄をチェックし直す
確認欄は、パスワード欄の値と比べます。ほかの欄の値は fieldApi.form.getFieldValue() で読めます。
<form.Field
name="confirmPassword"
validators={{
onChangeListenTo: ['password'],
onChange: ({ value, fieldApi }) =>
value !== fieldApi.form.getFieldValue('password')
? 'パスワードが一致しません'
: undefined,
}}
>
{/* 入力欄はメールアドレスと同じ形(type="password") */}
</form.Field>
onChange の入力チェックは、ふつうはその欄が変わったときにしか動きません。確認欄まで入れたあとでパスワード欄だけを書き換えると、2つの値が違うのにエラーが出ないままになります。onChangeListenTo: ['password'] を付けると、パスワード欄が変わったときにも確認欄の入力チェックが動きます(2つの欄を連動させる方法を書いた公式ドキュメントのページ)。
検証環境で、両方に「abcdefgh」と入れてからパスワード欄だけ「abcdefghX」にすると、onChangeListenTo を消した版では何も出ませんでした。付けた版では、確認欄の下に「パスワードが一致しません」が出ました。消した版でも、「登録する」を押せば入力チェックがやり直され、同じエラーが出て送信は止まりました。

GIF は、入力の動きが見えるように、撮影のときだけパスワードの2つの欄の文字を表示しています。
canSubmit でボタンを押せなくすると、理由が画面に出ないことがある
送信ボタンは、form.Subscribe で必要な状態だけを受け取って描きます。最初は、公式ドキュメントの入力チェックのページにある例にならって、送信できない(canSubmit が false)あいだはボタンを押せなくしました。
<form.Subscribe selector={(state) => [state.canSubmit, state.isSubmitting]}>
{([canSubmit, isSubmitting]) => (
<button type="submit" disabled={!canSubmit}>
{isSubmitting ? '送信中…' : '登録する'}
</button>
)}
</form.Subscribe>
この形で、メールアドレスとパスワード(8文字)だけを入れると、確認欄に触る前から「登録する」が押せなくなりました。画面にはエラーが1つも出ていません。
フォームの状態を見ると、確認欄は isTouched が false のまま、errors に「パスワードが一致しません」が入っていました。onChangeListenTo によって、パスワード欄の入力で確認欄の入力チェックが動き、空の確認欄を「一致しない」と判定したためです。canSubmit はこのエラーで false になりますが、FieldError は触っていない欄のエラーを出しません。フォームを使う人には、ボタンを押せない理由が分かりません。
ボタンを押せなくするのは送信中(isSubmitting)だけにして、エラーは「登録する」を押したときに見せる形にすると、この食い違いは起きません。
<form.Subscribe selector={(state) => state.isSubmitting}>
{(isSubmitting) => (
<button type="submit" disabled={isSubmitting}>
{isSubmitting ? '送信中…' : '登録する'}
</button>
)}
</form.Subscribe>
直した版で同じように入れて「登録する」を押すと、確認欄の下に「パスワードが一致しません」が出て、onSubmit は呼ばれませんでした。確認欄に「abcdefgh」を入れて押し直すと、送信が始まりました。なお、公式ドキュメントの入力チェックのページは、disabled のボタンはアクセシビリティの面で問題があるとして、aria-disabled を使うようすすめています。この記事のコードは、送信中だけ disabled を使っています。
送信中は「送信中…」を出し、二重送信を防ぐ
isSubmitting は、handleSubmit が入力チェックを始めてから onSubmit の Promise が終わるまで true です。検証環境では、「登録する」を押して0.1秒後にボタンが「送信中…」になって押せなくなり、送信が終わると「登録する」に戻りました。
メールアドレスの欄で Enter を押して送信し、送信中にさらに Enter を2回押しても、onSubmit が呼ばれたのは1回だけでした。HTML の仕様では、入力欄で Enter を押したときの送信は、最初の送信ボタンが disabled でなければ、そのボタンをクリックしたものとして扱う、と決められています。送信中はボタンが disabled なので、Enter を押しても送信されませんでした。
@tanstack/form-core 1.33.5 のソースでは、canSubmit は送信中(isSubmitting が true)のあいだも false になる作りでした。そのため最初の版でも、送信中はボタンが押せなくなっていました。





