ReactとTanStack Formで会員登録フォームを作る方法

​​React​TanStack Form,TypeScript,フォーム

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 に任せる

まず、パッケージを入れます。

bash
npm install @tanstack/react-form

フォームは useForm で作ります。defaultValues に初めの値を、onSubmit に送信の処理を渡します。defaultValues に型を付けておくと、フォームの値の型がそこから決まります。

tsx
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 のページ)。

tsx
<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 に文字列を渡したときもエラーになりました。

text
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 を見ているのは、まだ触っていない欄にエラーを出さないためです。

tsx
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 にしています。

tsx
<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() で読めます。

tsx
<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 を消した版では何も出ませんでした。付けた版では、確認欄の下に「パスワードが一致しません」が出ました。消した版でも、「登録する」を押せば入力チェックがやり直され、同じエラーが出て送信は止まりました。

上の帯に「操作 2回目/4回」などの表示が出る。パスワードと確認欄に abcdefgh を入れたあと、パスワード欄だけ末尾に X を足すと、確認欄の下に「パスワードが一致しません」が出る。X を消すとエラーが消え、「登録する」を押すとボタンが「送信中…」になり、送った値が表示されて入力欄が空に戻る
パスワード欄だけを書き換えたとき、確認欄のエラーが出て消えるまでと、送信の様子

GIF は、入力の動きが見えるように、撮影のときだけパスワードの2つの欄の文字を表示しています。

canSubmit でボタンを押せなくすると、理由が画面に出ないことがある

送信ボタンは、form.Subscribe で必要な状態だけを受け取って描きます。最初は、公式ドキュメントの入力チェックのページにある例にならって、送信できない(canSubmit が false)あいだはボタンを押せなくしました。

tsx
<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)だけにして、エラーは「登録する」を押したときに見せる形にすると、この食い違いは起きません。

tsx
<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 になる作りでした。そのため最初の版でも、送信中はボタンが押せなくなっていました。

​Posted by 86