React Hook Form

React Hook Form v7 リファレンス

React Hook Form v7 の全 API ドキュメントを網羅したスキル。 ユーザーのタスクに応じて適切な README.md を読み、そこから個別ファイルへ辿ること。

ディレクトリ構成

skills/react-hook-form/
  SKILL.md
  references/
    get-started/
      README.md
    api/
      README.md
      useform.md
      usecontroller.md
      useformcontext.md
      usewatch.md
      useformstate.md
      usefieldarray.md
      uselens.md
      createformcontrol.md
      useform-register.md
      useform-unregister.md
      useform-formstate.md
      useform-watch.md
      useform-subscribe.md
      useform-handlesubmit.md
      useform-reset.md
      useform-resetfield.md
      useform-resetdefaultvalues.md
      useform-seterror.md
      useform-clearerrors.md
      useform-setvalue.md
      useform-setvalues.md
      useform-setfocus.md
      useform-getvalues.md
      useform-getfieldstate.md
      useform-trigger.md
      useform-control.md
      useform-form.md
      controller.md
      formprovider.md
      watch-component.md
      errormessage.md
      formstatesubscribe.md
    typescript/
      README.md
    advanced/
      README.md
    faqs/
      README.md
    dev-tools/
      README.md
  samples/
    README.md
    basic-form.md
    schema-validation.md
    controlled-component.md
    field-array.md
    form-provider.md
    async-submit.md
    watch-conditional-fields.md
    reset-after-submit.md
    typescript-typed-form.md
  scripts/
    README.md
    install.md
    develop.md

探索手順

タスクからカテゴリを引き、カテゴリの README.md で目的のページを特定する:

1. 下記マッピング表でタスクに対応するカテゴリを探す 2. そのカテゴリの references/{category}/README.md を参照して目的のページを特定する 3. 該当ページの .md を Read して詳細を確認する

タスク → カテゴリ マッピング

Advanced

Controller

制御コンポーネント（React-Select、AntD、MUI など）をラップするためのコンポーネント。useController のコンポーネント版であり、render prop パターンでフィールドのバインディングを提供する。

シグネチャ

<Controller
  name={string}          // 必須
  control={Control}
  render={Function}      // 必須
  rules={Object}
  defaultValue={unknown}
  disabled={boolean}
  shouldUnregister={boolean}
  exact={boolean}
/>

Props

render 関数の引数

field オブジェクト

fieldState オブジェクト

formState オブジェクト

コード例

Web（React）での使用

import { useForm, Controller } from "react-hook-form";
import ReactDatePicker from "react-datepicker";

function App() {
  const { handleSubmit, control } = useForm({
    defaultValues: { dateField: new Date() },
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <Controller
        control={control}
        name="dateField"
        render={({ field: { onChange, onBlur, value } }) => (
          <ReactDatePicker
            onChange={onChange}
            onBlur={onBlur}
            selected={value}
          />
        )}
      />
      <button type="submit">送信</button>
    </form>
  );
}

React Native での使用

import { useForm, Controller } from "react-hook-form";
import { TextInput, Button, View } from "react-native";

function App() {
  const { handleSubmit, control } = useForm({
    defaultValues: { firstName: "" },
  });

  return (
    <View>
      <Controller
        control={control}
        name="firstName"
        rules={{ required: true }}
        render={({ field: { onChange, onBlur, value } }) => (
          <TextInput
            onChangeText={onChange}
            onBlur={onBlur}
            value={value}
          />
        )}
      />
      <Button title="送信" onPress={handleSubmit(console.log)} />
    </View>
  );
}

バリデーション付き

<Controller
  control={control}
  name="email"
  rules={{
    required: "メールアドレスは必須です",
    pattern: {
      value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i,
      message: "有効なメールアドレスを入力してください",
    },
  }}
  render={({ field, fieldState: { error } }) => (
    <div>
      <input {...field} />
      {error && <span>{error.message}</span>}
    </div>
  )}
/>

重要なルール

1. 二重登録の禁止: Controller と register() を同じフィールドに使用しないこと。Controller が内部でフィールド登録を行う。 2. 値のクリアには `null` か空文字を使用: onChange に undefined を渡してはならない。値をクリアする場合は null または "" を使用する。 3. defaultValues の設定: useForm の defaultValues でデフォルト値を一元管理することを推奨。dirty 状態の比較基準となる。 4. shouldUnregister と useFieldArray: shouldUnregister を useFieldArray と併用すると予期しない動作になるため避けること。

createFormControl

React Context を使わずにフォーム状態を作成する関数。v7.55.0 以降で利用可能。FormProvider でラップせずにフォームメソッドを直接使用でき、subscribe でコンポーネントの再レンダリングなしにフォーム状態を購読できる。

バージョン要件

• v7.55.0+（オプション機能）

シグネチャ

createFormControl<TFieldValues>(
  props?: UseFormProps<TFieldValues>
): CreateFormControlReturn<TFieldValues>

引数

Return

コード例

基本的な使い方

import { createFormControl } from "react-hook-form";

// フォーム制御をコンポーネント外で作成
const {
  register,
  handleSubmit,
  control,
  formState,
  subscribe,
} = createFormControl({
  defaultValues: {
    firstName: "",
    lastName: "",
    email: "",
  },
});

function App() {
  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <input {...register("firstName")} />
      <input {...register("lastName")} />
      <input {...register("email")} />
      <button type="submit">送信</button>
    </form>
  );
}

subscribe による再レンダリングなしの購読

const { register, handleSubmit, subscribe } = createFormControl({
  defaultValues: { name: "" },
});

// 再レンダリングなしでフォーム状態を購読
const unsubscribe = subscribe({
  formState: {
    // 購読したい状態を指定
    isDirty: true,
    errors: true,
  },
  callback: (formState) => {
    // フォーム状態が変更されたときに呼ばれる
    console.log("isDirty:", formState.isDirty);
    console.log("errors:", formState.errors);

    // DOM を直接操作するなど、React 外の処理に有用
    document.getElementById("status").textContent = formState.isDirty
      ? "変更あり"
      : "変更なし";
  },
});

// 不要になったら購読解除
unsubscribe();

useForm の formControl と統合

import { useForm, createFormControl } from "react-hook-form";

const { formControl } = createFormControl({
  defaultValues: { name: "" },
});

function App() {
  // formControl を useForm に渡して統合
  const { register, handleSubmit } = useForm({
    formControl,
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input {...register("name")} />
      <button type="submit">送信</button>
    </form>
  );
}

useController との併用

import { useController } from "react-hook-form";

const { control, handleSubmit } = createFormControl({
  defaultValues: { date: new Date() },
});

function DateField() {
  const { field } = useController({
    control,
    name: "date",
  });

  return (
    <DatePicker
      value={field.value}
      onChange={field.onChange}
    />
  );
}

重要なルール

1. Context API か createFormControl のどちらかを使う: 両方を同時に使用しないこと。createFormControl を使用する場合は FormProvider でラップしない。

2. FormProvider は不要: createFormControl はコンポーネントツリー外でフォーム状態を作成するため、FormProvider によるラップが不要。メソッドを直接インポートして使用できる。

3. subscribe の用途: subscribe はコンポーネントの再レンダリングをトリガーせずにフォーム状態の変更を購読する。パフォーマンスが重要な場面や、DOM 直接操作、外部ライブラリとの統合に適している。

4. オプション機能: createFormControl は完全にオプションであり、従来の useForm + useFormContext パターンの代替手段として提供される。

5. 非 React 環境: React コンポーネント外でフォーム状態が必要な場合（例: ユーティリティ関数、外部ライブラリ統合）に特に有用。

ErrorMessage

React Hook Form のエラーメッセージを表示するためのコンポーネント。@hookform/error-message パッケージとして提供される。

インストール

npm install @hookform/error-message

シグネチャ

import { ErrorMessage } from "@hookform/error-message";

<ErrorMessage
  name={string}           // 必須
  errors={object}
  message={string | ReactElement}
  as={ReactElementType | string}
  render={Function}
/>

Props

コード例

基本的な使い方（単一エラー）

import { useForm } from "react-hook-form";
import { ErrorMessage } from "@hookform/error-message";

function App() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm({
    defaultValues: { name: "" },
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input
        {...register("name", { required: "名前は必須です" })}
      />
      <ErrorMessage errors={errors} name="name" />
      <button type="submit">送信</button>
    </form>
  );
}

render prop でカスタム表示

<ErrorMessage
  errors={errors}
  name="email"
  render={({ message }) => <p className="error">{message}</p>}
/>

as prop でラッパー要素を指定

<ErrorMessage
  errors={errors}
  name="email"
  as="span"
/>

message prop でインラインメッセージ

<input {...register("name", { required: true })} />
<ErrorMessage
  errors={errors}
  name="name"
  message="このフィールドは必須です"
/>

複数エラーモード（criteriaMode: "all"）

useForm の criteriaMode を "all" に設定すると、1 つのフィールドに対する複数のバリデーションエラーを同時に表示できる。

import { useForm } from "react-hook-form";
import { ErrorMessage } from "@hookform/error-message";

function App() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm({
    criteriaMode: "all", // 全エラーを収集
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input
        {...register("password", {
          required: "パスワードは必須です",
          minLength: {
            value: 8,
            message: "8文字以上で入力してください",
          },
          pattern: {
            value: /[A-Z]/,
            message: "大文字を1文字以上含めてください",
          },
        })}
      />
      <ErrorMessage
        errors={errors}
        name="password"
        render={({ messages }) =>
          messages &&
          Object.entries(messages).map(([type, message]) => (
            <p key={type} className="error">
              {message}
            </p>
          ))
        }
      />
      <button type="submit">送信</button>
    </form>
  );
}

重要なルール

1. criteriaMode の設定: 複数エラーを同時表示するには useForm で criteriaMode: "all" を設定する必要がある。デフォルトの "firstError" では最初のエラーのみ返される。 2. render の引数: 単一エラーモードでは { message } を受け取り、複数エラーモードでは { messages } オブジェクトを受け取る。messages は { [validationType]: message } の形式。 3. FormProvider との併用: FormProvider 使用時は errors prop を省略できる。コンテキストから自動的にエラー情報を取得する。 4. エラーが存在しない場合: 対象フィールドにエラーがない場合、コンポーネントは何もレンダリングしない。

FormProvider

useForm の全メソッドを React Context 経由で子コンポーネントに配信するプロバイダーコンポーネント。深くネストされたコンポーネントで useFormContext を使ってフォームメソッドにアクセスするために使用する。

シグネチャ

<FormProvider {...methods}>
  {children}
</FormProvider>

Props

配信されるメソッド

FormProvider 経由で子コンポーネントに提供されるメソッド一覧:

コード例

基本的な使い方

import { useForm, FormProvider, useFormContext } from "react-hook-form";

function App() {
  const methods = useForm({
    defaultValues: {
      firstName: "",
      lastName: "",
      email: "",
    },
  });

  const onSubmit = (data) => console.log(data);

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <PersonalInfo />
        <ContactInfo />
        <button type="submit">送信</button>
      </form>
    </FormProvider>
  );
}

function PersonalInfo() {
  const { register } = useFormContext();
  return (
    <div>
      <input {...register("firstName")} placeholder="名前" />
      <input {...register("lastName")} placeholder="姓" />
    </div>
  );
}

function ContactInfo() {
  const { register } = useFormContext();
  return <input {...register("email")} placeholder="メール" />;
}

handleSubmit の使用

function App() {
  const methods = useForm();

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit((data) => console.log(data))}>
        <NestedFields />
        <SubmitButton />
      </form>
    </FormProvider>
  );
}

function SubmitButton() {
  const { formState: { isSubmitting } } = useFormContext();
  return (
    <button type="submit" disabled={isSubmitting}>
      {isSubmitting ? "送信中..." : "送信"}
    </button>
  );
}

重要なルール

1. スプレッド演算子で全メソッドを渡す: useForm の返り値を {...methods} でスプレッドして渡すこと。個別のプロパティだけを渡すと useFormContext が正しく動作しない。

// OK
<FormProvider {...methods}>

// NG: 個別に渡さない
<FormProvider control={methods.control} register={methods.register}>

2. ネストした FormProvider は避ける: 複数の FormProvider をネストすると、コンテキストの競合が発生する。1 つのフォームには 1 つの FormProvider を使用する。

// NG: ネストしない
<FormProvider {...methodsA}>
  <FormProvider {...methodsB}>
    {/* コンテキスト競合 */}
  </FormProvider>
</FormProvider>

3. useEffect 依存配列の注意: FormProvider から取得したメソッドオブジェクト全体を useEffect の依存配列に入れないこと。必要な個別メソッド（例: reset）のみを指定する。

FormStateSubscribe

useFormState フックのコンポーネント版。render prop パターンを使い、JSX 内で宣言的にフォーム状態を購読できる。購読したフィールドの状態が変更された時のみ再レンダリングされる。

シグネチャ

<FormStateSubscribe
  control={Control}
  name={string | string[]}  // 必須
  disabled={boolean}
  exact={boolean}
  render={Function}          // 必須
/>

Props

render 関数の引数

render 関数は formState オブジェクトを受け取る。

コード例

基本的な使い方

import { useForm, FormStateSubscribe } from "react-hook-form";

function App() {
  const { register, control } = useForm({
    defaultValues: { foo: "", bar: "" },
  });

  return (
    <form>
      <input {...register("foo", { required: "必須です" })} />
      <input {...register("bar")} />

      <FormStateSubscribe
        control={control}
        name="foo"
        render={({ errors }) => (
          <span>{errors.foo?.message}</span>
        )}
      />
    </form>
  );
}

送信状態の表示

<FormStateSubscribe
  control={control}
  name={["firstName", "lastName"]}
  render={({ isSubmitting, isValid }) => (
    <button type="submit" disabled={isSubmitting || !isValid}>
      {isSubmitting ? "送信中..." : "送信"}
    </button>
  )}
/>

dirty 状態の表示

<FormStateSubscribe
  control={control}
  name="email"
  exact={true}
  render={({ dirtyFields, errors }) => (
    <div>
      {dirtyFields.email && <span>変更あり</span>}
      {errors.email && <span className="error">{errors.email.message}</span>}
    </div>
  )}
/>

FormProvider との併用

import { useForm, FormProvider, FormStateSubscribe } from "react-hook-form";

function App() {
  const methods = useForm();

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <input {...methods.register("name")} />
        <StatusDisplay />
      </form>
    </FormProvider>
  );
}

function StatusDisplay() {
  // FormProvider 内では control 不要
  return (
    <FormStateSubscribe
      name="name"
      render={({ isDirty, errors }) => (
        <div>
          {isDirty && <p>フォームが変更されています</p>}
          {errors.name && <p>{errors.name.message}</p>}
        </div>
      )}
    />
  );
}

重要なルール

1. render prop は必須: render 関数は必ず指定する。フォーム状態オブジェクトを引数として受け取り、React 要素を返す。 2. 選択的な再レンダリング: 指定したフィールドの状態が変更された時のみ再レンダリングされるため、パフォーマンスに優れる。 3. useFormState との使い分け: フックが使えない場面や、JSX 内で宣言的に状態を表示したい場合に FormStateSubscribe が適している。ロジック処理が必要な場合は useFormState を使用する。 4. exact の活用: exact: true を指定すると、指定したフィールド名に完全一致する状態変更のみで再レンダリングがトリガーされる。ネストされたフィールド名がある場合に有用。

API

useController

制御コンポーネント（React-Select、AntD、MUI など）を React Hook Form と統合するためのカスタムフック。register が使えない外部コンポーネントに対して、フォーム状態の接続を提供する。

シグネチャ

useController(props?: UseControllerProps): {
  field: UseControllerReturn['field'];
  fieldState: UseControllerReturn['fieldState'];
  formState: UseControllerReturn['formState'];
}

Props

Return

field オブジェクト

fieldState オブジェクト

formState オブジェクト

コード例

基本的な使い方

import { useController, useForm } from "react-hook-form";

function TextField({ name, control, rules }) {
  const {
    field,
    fieldState: { invalid, error },
  } = useController({
    name,
    control,
    rules: { required: true },
  });

  return (
    <div>
      <input
        onChange={field.onChange}
        onBlur={field.onBlur}
        value={field.value}
        name={field.name}
        ref={field.ref}
      />
      {invalid && <p>{error?.message}</p>}
    </div>
  );
}

function App() {
  const { handleSubmit, control } = useForm({
    defaultValues: { firstName: "" },
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <TextField name="firstName" control={control} rules={{ required: true }} />
      <button type="submit">送信</button>
    </form>
  );
}

チェックボックス（配列値）パターン

function Checkboxes({ name, control, options }) {
  const { field } = useController({ control, name });
  const [value, setValue] = useState(field.value || []);

  return (
    <>
      {options.map((option) => (
        <label key={option}>
          <input
            type="checkbox"
            value={option}
            checked={value.includes(option)}
            onChange={(e) => {
              const newValue = e.target.checked
                ? [...value, option]
                : value.filter((v) => v !== option);
              setValue(newValue);
              field.onChange(newValue);
            }}
          />
          {option}
        </label>
      ))}
    </>
  );
}

重要なルール

1. 二重登録の禁止: {...field} と {...register()} を同じフィールドに同時使用しないこと。useController がフィールド登録を管理する。 2. 単一インスタンス: 1 つのコンポーネントに対して 1 つの useController を使用する。複数必要な場合はリネームする。 3. defaultValue に `undefined` は不可: defaultValue には undefined を使用できない。フォームレベルの defaultValues で設定すること。 4. dirty 状態の追跡: isDirty を正確に追跡するには、フォームレベルで defaultValues を設定する必要がある。 5. ローカル状態との併用: useState と組み合わせて UI 状態を管理できる（上記チェックボックス例を参照）。

useFieldArray

動的なフォームフィールド（追加・削除・並べ替え）を管理するためのカスタムフック。パフォーマンスとユーザー体験を最適化した配列操作を提供する。

シグネチャ

useFieldArray(props: UseFieldArrayProps): UseFieldArrayReturn

Props

Return

コード例

基本的な使い方

import { useForm, useFieldArray } from "react-hook-form";

function App() {
  const { register, control, handleSubmit } = useForm({
    defaultValues: {
      items: [{ name: "" }],
    },
  });

  const { fields, append, remove } = useFieldArray({
    control,
    name: "items",
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      {fields.map((field, index) => (
        <div key={field.id}>
          <input {...register(`items.${index}.name`)} />
          <button type="button" onClick={() => remove(index)}>
            削除
          </button>
        </div>
      ))}
      <button type="button" onClick={() => append({ name: "" })}>
        追加
      </button>
      <button type="submit">送信</button>
    </form>
  );
}

ネストされたフィールド配列

function NestedFieldArray({ nestIndex, control, register }) {
  const { fields, append, remove } = useFieldArray({
    control,
    name: `items.${nestIndex}.subItems`,
  });

  return (
    <div>
      {fields.map((field, index) => (
        <div key={field.id}>
          <input
            {...register(`items.${nestIndex}.subItems.${index}.value`)}
          />
          <button type="button" onClick={() => remove(index)}>
            削除
          </button>
        </div>
      ))}
      <button type="button" onClick={() => append({ value: "" })}>
        サブアイテム追加
      </button>
    </div>
  );
}

バリデーション付き

const { fields, append } = useFieldArray({
  control,
  name: "items",
  rules: {
    required: "最低1つのアイテムが必要です",
    minLength: {
      value: 1,
      message: "最低1つのアイテムが必要です",
    },
    maxLength: {
      value: 10,
      message: "アイテムは10個までです",
    },
  },
});

操作の組み合わせ

// 複数のフィールドを一括追加
append([{ name: "アイテム1" }, { name: "アイテム2" }]);

// フィールドの入れ替え
swap(0, 1);

// フィールドの移動
move(2, 0); // index 2 を index 0 に移動

// 指定位置に挿入
insert(1, { name: "挿入アイテム" });

// 特定のフィールドを更新
update(0, { name: "更新された値" });

// フィールド配列全体を置き換え
replace([{ name: "新アイテム1" }, { name: "新アイテム2" }]);

// 複数のフィールドを削除
remove([0, 2]); // index 0 と 2 を削除

// 全フィールドを削除
remove();

重要なルール

1. key には `field.id` を使用する: 配列の index ではなく、field.id を React の key に使用すること。

// OK
{fields.map((field, index) => (
  <div key={field.id}>...</div>
))}

// NG: index を key に使わない
{fields.map((field, index) => (
  <div key={index}>...</div>
))}

2. defaultValues の設定が必須: useForm で配列フィールドの defaultValues を設定する必要がある。

const { control } = useForm({
  defaultValues: {
    items: [{ name: "" }], // 必須
  },
});

3. append/prepend/insert/update には完全なオブジェクトを渡す: 全てのプロパティを含むオブジェクトを渡すこと。空オブジェクトや部分的なデータは不可。

// OK
append({ name: "", email: "" });

// NG: 空オブジェクト
append({});

4. 複数操作は useEffect 内で: remove などのアクションは 2 回目のレンダリング後に実行されるため、複数の操作を順次実行する場合は useEffect 内で行う。

// NG: onClick 内で複数操作をスタックしない
onClick={() => {
  remove(0);
  remove(1); // 意図通りに動作しない
}}

// OK: useEffect 内で
useEffect(() => {
  remove(0);
}, [condition]);

5. 1 つの名前に 1 つの useFieldArray: 同じフィールド名に対して複数の useFieldArray を使用しないこと。

6. フラット配列と循環参照は非サポート: フィールド配列はオブジェクトの配列である必要がある。フラットな値の配列（string[] など）や循環参照はサポートされない。

7. TypeScript での型アサーション: ネストされた配列のパスは as const でキャストする。

{...register(`items.${index}.name` as const)}

useForm — clearErrors

clearErrors メソッドはフォームのエラーをクリアする。全エラー、単一フィールド、または複数フィールドのエラーを選択的に削除可能。

シグネチャ

clearErrors: (name?: string | string[]) => void

引数

引数パターン

コード例

全エラーのクリア

import { useForm } from "react-hook-form";

function App() {
  const {
    register,
    clearErrors,
    setError,
    formState: { errors },
  } = useForm();

  return (
    <form>
      <input {...register("firstName", { required: true })} />
      {errors.firstName && <span>必須です</span>}

      <input {...register("lastName", { required: true })} />
      {errors.lastName && <span>必須です</span>}

      <button type="button" onClick={() => clearErrors()}>
        全エラーをクリア
      </button>
    </form>
  );
}

単一フィールドのクリア

clearErrors("firstName");

複数フィールドのクリア

clearErrors(["firstName", "lastName"]);

ネストフィールドの親指定でクリア

// "test" を指定すると、test.firstName と test.lastName のエラーも削除される
clearErrors("test");

// 特定の子フィールドのみ削除する場合
clearErrors("test.firstName");

setError と組み合わせた使用

const onSubmit = async (data: any) => {
  // 送信前にサーバーエラーをクリア
  clearErrors("root.serverError");

  try {
    await submitData(data);
  } catch {
    setError("root.serverError", {
      type: "server",
      message: "送信に失敗しました",
    });
  }
};

重要なルール / 注意事項

• バリデーションルール自体には影響しない。エラー表示をクリアするだけで、register で設定されたルールは維持される。
• isValid の formState プロパティには直接影響しない。有効性はバリデーションルールに基づいて再評価される。
• ネストフィールドの親名を指定すると、その配下の全子フィールドのエラーもクリアされる。
• setError で手動設定したエラーをクリアする場合にも使用する。

useForm — control

control はフォームの内部制御を管理するオブジェクトで、Controller、useWatch、useFormState、useFieldArray などのコンポーネントやフックに渡して使用する。

取得方法

const { control } = useForm();

用途

コード例

Controller での使用

import { useForm, Controller } from "react-hook-form";

function App() {
  const { control, handleSubmit } = useForm({
    defaultValues: { firstName: "" },
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <Controller
        name="firstName"
        control={control}
        rules={{ required: "名前は必須です" }}
        render={({ field, fieldState: { error } }) => (
          <div>
            <input {...field} />
            {error && <span>{error.message}</span>}
          </div>
        )}
      />
      <input type="submit" />
    </form>
  );
}

useWatch での使用

import { useForm, useWatch } from "react-hook-form";

function WatchedField({ control }: { control: Control }) {
  const firstName = useWatch({ control, name: "firstName" });
  return <p>現在の値: {firstName}</p>;
}

function App() {
  const { control, register } = useForm({
    defaultValues: { firstName: "" },
  });

  return (
    <form>
      <input {...register("firstName")} />
      <WatchedField control={control} />
    </form>
  );
}

useFieldArray での使用

import { useForm, useFieldArray } from "react-hook-form";

function App() {
  const { control, register } = useForm({
    defaultValues: { items: [{ name: "" }] },
  });

  const { fields, append, remove } = useFieldArray({
    control,
    name: "items",
  });

  return (
    <form>
      {fields.map((field, index) => (
        <input key={field.id} {...register(`items.${index}.name`)} />
      ))}
      <button type="button" onClick={() => append({ name: "" })}>
        追加
      </button>
    </form>
  );
}

重要なルール / 注意事項

• control オブジェクトの内部プロパティに直接アクセスしてはならない。内部実装用であり、APIが変更される可能性がある。
• control は useForm から取得し、必要なコンポーネントやフックに prop として渡す。
• useFormContext を使用すると、control を prop として渡す代わりにコンテキスト経由で取得できる。

useForm — Form

Form コンポーネント（Beta）はフォーム送信を管理するラッパーコンポーネントで、標準の HTML <form> 要素と密接に連携する。デフォルトで POST リクエストを FormData で送信する。

シグネチャ

<Form
  control={control}
  action="/api/endpoint"
  onSubmit={onSubmitHandler}
  onSuccess={onSuccessHandler}
  onError={onErrorHandler}
  headers={headers}
  validateStatus={validateStatus}
  method="post"
  render={renderProp}
>
  {children}
</Form>

Props

コード例

React Web — action prop での使用

import { useForm, Form } from "react-hook-form";

function App() {
  const { register, control } = useForm({
    defaultValues: { name: "", email: "" },
  });

  return (
    <Form
      action="/api/submit"
      control={control}
      onSuccess={() => {
        alert("送信成功！");
      }}
      onError={() => {
        alert("送信に失敗しました");
      }}
    >
      <input {...register("name")} />
      <input {...register("email")} />
      <button type="submit">送信</button>
    </Form>
  );
}

React Web — 手動送信

import { useForm, Form } from "react-hook-form";

function App() {
  const { register, control } = useForm();

  return (
    <Form
      onSubmit={async ({ formData, data, event }) => {
        await fetch("/api/submit", {
          method: "POST",
          body: formData,
        });
      }}
    >
      <input {...register("name")} />
      <button type="submit">送信</button>
    </Form>
  );
}

JSON での送信

<Form
  action="/api/submit"
  control={control}
  headers={{
    "Content-Type": "application/json",
  }}
  onSuccess={() => console.log("成功")}
>
  <input {...register("name")} />
  <button type="submit">送信</button>
</Form>

React Native での使用

import { useForm, Form } from "react-hook-form";
import { View, TextInput, Button } from "react-native";

function App() {
  const { register, control } = useForm();

  return (
    <Form
      action="/api/submit"
      control={control}
      render={({ submit }) => (
        <View>
          <TextInput {...register("name")} />
          <Button title="送信" onPress={() => submit()} />
        </View>
      )}
    />
  );
}

バリデーションステータスのカスタマイズ

<Form
  action="/api/submit"
  control={control}
  validateStatus={(status) => status >= 200 && status < 300}
>
  ...
</Form>

重要なルール / 注意事項

• デフォルトでは POST メソッドで FormData として送信する。JSON で送信するには headers に Content-Type: application/json を指定する。
• onSubmit コールバックまたは handleSubmit を使用して、送信前にデータを加工または除外できる。
• プログレッシブエンハンスメントは SSR フレームワークでのみ機能し、useForm の progressive: true オプションが必要。
• Beta 機能であるため、API が変更される可能性がある。
• React Native では render prop を使用し、submit 関数を明示的に呼び出す。
• onError が呼ばれた場合、root.server エラーが自動的に formState.errors に設定される。

useForm — formState

formState はフォーム全体の状態情報を格納するオブジェクトで、ユーザーの操作状況やバリデーション結果を追跡する。パフォーマンス最適化のため Proxy でラップされている。

プロパティ

Proxy による購読の仕組み

formState は JavaScript の Proxy でラップされており、実際にアクセスされたプロパティのみが購読される。これにより、未使用のプロパティの変更では再レンダリングが発生しない。

正しい使い方

// レンダリング前にプロパティをデストラクチャリングする
const { isDirty, errors } = formState;

// または直接アクセスする
return <p>{formState.errors.name?.message}</p>;

誤った使い方

// 条件付きアクセスは購読が登録されない可能性がある
if (someCondition) {
  formState.isDirty; // 購読が不安定
}

コード例

基本的な使い方

import { useForm } from "react-hook-form";

function App() {
  const {
    register,
    handleSubmit,
    formState: {
      errors,
      isDirty,
      isSubmitting,
      isValid,
      touchedFields,
      dirtyFields,
    },
  } = useForm({
    mode: "onChange",
    defaultValues: { firstName: "", email: "" },
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input {...register("firstName", { required: true })} />
      {errors.firstName && <span>必須フィールドです</span>}

      <button type="submit" disabled={!isDirty || !isValid || isSubmitting}>
        送信
      </button>
    </form>
  );
}

useEffect での使用

// formState 全体を依存配列に含める
const { formState } = useForm();

useEffect(() => {
  if (formState.isSubmitSuccessful) {
    reset();
  }
}, [formState, reset]);

重要なルール / 注意事項

• Proxy が機能するには、レンダリング前にプロパティにアクセスまたはデストラクチャリングする必要がある。
• useEffect の依存配列には formState 全体を含めること。個別プロパティではなく全体を指定する。
• 論理演算子で条件付きにアクセスすると、Proxy の購読が正しく動作しない場合がある。値はデストラクチャリングで取り出すこと。
• isDirty を正確に機能させるには、useForm で全入力の defaultValues を提供する必要がある。
• ファイル入力はアプリケーションレベルで管理する必要がある。
• カスタムオブジェクトや File インスタンスは dirty 追跡に対応していない。

useForm — getFieldState

getFieldState メソッドは個別フィールドの状態（dirty, touched, エラー）を取得する。v7.25.0 以降で利用可能。

シグネチャ

getFieldState: (
  name: string,
  formState?: FormState
) => {
  isDirty: boolean;
  isTouched: boolean;
  invalid: boolean;
  error: FieldError | undefined;
}

引数

戻り値

コード例

useForm と組み合わせた使用

import { useForm } from "react-hook-form";

function App() {
  const {
    register,
    getFieldState,
    formState,
    formState: { isDirty, errors },
  } = useForm({
    mode: "onChange",
    defaultValues: { firstName: "" },
  });

  // formState を購読済みなので第2引数は不要
  const fieldState = getFieldState("firstName");

  return (
    <form>
      <input {...register("firstName", { required: true })} />
      <p>isDirty: {fieldState.isDirty ? "はい" : "いいえ"}</p>
      <p>isTouched: {fieldState.isTouched ? "はい" : "いいえ"}</p>
      <p>invalid: {fieldState.invalid ? "はい" : "いいえ"}</p>
      {fieldState.error && <p>エラー: {fieldState.error.message}</p>}
    </form>
  );
}

formState を明示的に渡す

const { getFieldState, formState } = useForm();

// formState を第2引数に渡す
const fieldState = getFieldState("firstName", formState);

useFormContext と組み合わせた使用

import { useFormContext } from "react-hook-form";

function FieldInfo({ name }: { name: string }) {
  const { getFieldState, formState } = useFormContext();
  const { isDirty, error } = getFieldState(name, formState);

  return (
    <div>
      {isDirty && <span>変更あり</span>}
      {error && <span>{error.message}</span>}
    </div>
  );
}

useFormState と組み合わせた使用

import { useForm, useFormState } from "react-hook-form";

function App() {
  const { register, control, getFieldState } = useForm();
  const formState = useFormState({ control });

  const { isDirty, isTouched } = getFieldState("firstName", formState);
}

重要なルール / 注意事項

• v7.25.0 以降で利用可能。
• フィールド名が登録済みのフィールドに一致しない場合、isDirty: false、isTouched: false、invalid: false、error: undefined が返される。
• formState の購読が前提条件。以下のいずれかの方法で購読が必要:
• useForm() から formState をデストラクチャリング
• useFormContext() で formState を取得
• useFormState() で formState を取得
• 第2引数に formState を直接渡す
• 購読されていない formState プロパティに対応する戻り値は正確でない場合がある。

useForm — getValues

getValues メソッドはフォームの値を取得する。watch と異なり、再レンダリングをトリガーせず、入力変更の購読も行わない。

シグネチャ

getValues: (payload?: string | string[]) => Object

引数

引数パターン

コード例

全フォーム値の取得

import { useForm } from "react-hook-form";

function App() {
  const { register, getValues } = useForm({
    defaultValues: { firstName: "太郎", lastName: "山田" },
  });

  const handleClick = () => {
    const values = getValues();
    console.log(values);
    // { firstName: "太郎", lastName: "山田" }
  };

  return (
    <form>
      <input {...register("firstName")} />
      <input {...register("lastName")} />
      <button type="button" onClick={handleClick}>
        値を取得
      </button>
    </form>
  );
}

単一フィールドの取得

const firstName = getValues("firstName");
// "太郎"

複数フィールドの取得

const [firstName, lastName] = getValues(["firstName", "lastName"]);
// ["太郎", "山田"]

ネストフィールドの取得

const email = getValues("user.email");
const firstItem = getValues("items.0.title");

dirty フィールドのみ取得

const dirtyValues = getValues(undefined, { dirtyFields: true });

touched フィールドのみ取得

const touchedValues = getValues(undefined, { touchedFields: true });

条件分岐での使用

const onSubmit = () => {
  const type = getValues("type");
  if (type === "premium") {
    // プレミアム向け処理
  }
};

重要なルール / 注意事項

• 再レンダリングをトリガーしない。また、入力変更を購読しない。値の変更に応じて UI を更新する場合は watch または useWatch を使用すること。
• 初回レンダリング前（register の前）は useForm の defaultValues を返す。
• イベントハンドラやコールバック内で現在のフォーム値を取得する場合に最適。
• リアクティブな値の監視には適さない。

useForm — handleSubmit

handleSubmit メソッドはフォーム送信を処理する。バリデーションを実行し、成功時とエラー時のコールバックを呼び分ける。

シグネチャ

handleSubmit: (
  onValid: SubmitHandler<TFieldValues>,
  onInvalid?: SubmitErrorHandler<TFieldValues>
) => (e?: React.BaseSyntheticEvent) => Promise<void>

型定義

type SubmitHandler<TFieldValues> = (
  data: TFieldValues,
  event?: React.BaseSyntheticEvent
) => void | Promise<void>;

type SubmitErrorHandler<TFieldValues> = (
  errors: FieldErrors<TFieldValues>,
  event?: React.BaseSyntheticEvent
) => void | Promise<void>;

引数

コード例

基本的な使い方

import { useForm } from "react-hook-form";

function App() {
  const { register, handleSubmit } = useForm();

  const onSubmit = (data: any, e?: React.BaseSyntheticEvent) => {
    console.log("送信データ:", data);
  };

  const onError = (errors: any, e?: React.BaseSyntheticEvent) => {
    console.log("バリデーションエラー:", errors);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit, onError)}>
      <input {...register("firstName", { required: true })} />
      <input type="submit" />
    </form>
  );
}

非同期送信と try-catch

const onSubmit = async (data: FormValues) => {
  try {
    const response = await fetch("/api/submit", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });
    if (!response.ok) throw new Error("送信失敗");
  } catch (error) {
    // エラーハンドリングを実装すること
    console.error(error);
  }
};

return <form onSubmit={handleSubmit(onSubmit)}>...</form>;

ボタンクリックでの呼び出し

<button onClick={handleSubmit(onSubmit)}>送信</button>

重要なルール / 注意事項

• handleSubmit は非同期コールバックをサポートする。async/await が使用可能。
• handleSubmit は内部で発生したエラーを飲み込まない。onSubmit コールバック内で非同期リクエストを行う場合は、必ず try-catch でエラーハンドリングすること。
• disabled な input のフォームデータ値は undefined になる。値を保持したい場合は disabled ではなく readOnly を使用するか、<fieldset disabled> で囲む。
• handleSubmit の戻り値は Promise<void> であるため、event.preventDefault() は自動的に呼ばれる。

useForm — register

register メソッドは input 要素をフォームに登録し、バリデーションルールを適用する。戻り値を input 要素にスプレッドすることで、値の追跡と検証が可能になる。

シグネチャ

register: (name: string, options?: RegisterOptions) => {
  ref: React.Ref;
  name: string;
  onChange: ChangeHandler;
  onBlur: ChangeHandler;
}

引数

オプション

戻り値

ネストフィールド記法

コード例

基本的な使い方

import { useForm } from "react-hook-form";

function App() {
  const { register, handleSubmit, formState: { errors } } = useForm({
    defaultValues: { firstName: "", email: "" },
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input {...register("firstName", { required: "名前は必須です" })} />
      {errors.firstName && <p>{errors.firstName.message}</p>}

      <input
        {...register("email", {
          required: "メールは必須です",
          pattern: {
            value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
            message: "有効なメールアドレスを入力してください",
          },
        })}
      />
      {errors.email && <p>{errors.email.message}</p>}

      <input type="submit" />
    </form>
  );
}

カスタムバリデーション

<input
  {...register("username", {
    validate: {
      checkLength: (value) =>
        value.length >= 3 || "ユーザー名は3文字以上必要です",
      checkFormat: (value) =>
        /^[a-zA-Z0-9]+$/.test(value) || "英数字のみ使用可能です",
    },
  })}
/>

非同期バリデーション

<input
  {...register("email", {
    validate: async (value) => {
      const response = await fetch(`/api/check-email?email=${value}`);
      const { available } = await response.json();
      return available || "このメールアドレスは既に使用されています";
    },
  })}
/>

値の変換

<input
  type="number"
  {...register("age", { valueAsNumber: true, min: 18 })}
/>

<input
  {...register("price", {
    setValueAs: (v) => parseInt(v, 10),
  })}
/>

依存フィールド

<input {...register("password")} type="password" />
<input
  {...register("confirmPassword", {
    deps: ["password"],
    validate: (value, formValues) =>
      value === formValues.password || "パスワードが一致しません",
  })}
  type="password"
/>

重要なルール / 注意事項

• フィールド名は一意でなければならず、数字で始めることはできない。
• ネストフィールドにはドット記法を使用する（ブラケット記法ではなく）。
• disabled な入力のフォームデータ値は undefined になる。
• 個別のオプションを削除することはできない。false に更新する必要がある。
• 予約語 ref、_f をフィールド名として使用しないこと。
• valueAsNumber、valueAsDate、setValueAs は互いに排他的。

useForm — reset

reset メソッドはフォーム全体の状態（値、エラー、dirty 状態など）をリセットする。オプションで特定の状態のみ保持しつつリセットすることも可能。

シグネチャ

reset: <T extends FieldValues>(
  values?: T | ResetAction<T>,
  options?: KeepStateOptions
) => void

引数

オプション

コード例

基本的なリセット

const { register, handleSubmit, reset } = useForm({
  defaultValues: { firstName: "", lastName: "" },
});

// デフォルト値にリセット
reset();

// 新しい値でリセット（defaultValues も更新）
reset({ firstName: "太郎", lastName: "山田" });

特定の状態を保持してリセット

// dirty なフィールドの値を保持
reset(undefined, { keepDirtyValues: true });

// エラーを保持してリセット
reset(undefined, { keepErrors: true });

// 値を保持して状態のみリセット
reset(undefined, { keepValues: true });

送信成功後のリセット

const { handleSubmit, reset, formState } = useForm();

useEffect(() => {
  if (formState.isSubmitSuccessful) {
    reset();
  }
}, [formState.isSubmitSuccessful, reset]);

関数でリセット値を計算

reset((formValues) => ({
  ...formValues,
  firstName: "リセット済み",
}));

外部データでリセット

useEffect(() => {
  async function fetchData() {
    const response = await fetch("/api/user");
    const data = await response.json();
    reset(data);
  }
  fetchData();
}, [reset]);

重要なルール / 注意事項

• Controller コンポーネントをリセットするには、useForm に defaultValues を提供する必要がある。
• useForm の useEffect が実行される前に reset を呼び出してはならない。サブスクリプションの初期化が必要。
• 送信成功後のリセットは useEffect 内で行い、実行順序を保証すること。
• reset に値を渡すと、defaultValues も更新される（keepDefaultValues: true を指定しない限り）。
• values を渡さず options のみ渡す場合は、第1引数に undefined を指定する。

useForm — resetDefaultValues

resetDefaultValues メソッドはフォームのデフォルト値を更新し、それに伴い dirty/valid 状態を再計算する。v7.77.0 以降で利用可能。reset() と異なり、ユーザーが入力した値には影響せず、デフォルト値の基準線のみを更新する。

バージョン要件

• v7.77.0+

シグネチャ

resetDefaultValues: (
  values: DefaultValues<TFieldValues> | TFieldValues,
  options?: {
    keepDirty?: boolean;
    keepIsValid?: boolean;
  }
) => void

引数

オプション

reset() との違い

コード例

サーバーデータでデフォルト値を更新

import { useForm } from "react-hook-form";

type FormValues = {
  firstName: string;
  lastName: string;
  email: string;
};

function UserProfileForm({ userId }: { userId: string }) {
  const { register, handleSubmit, resetDefaultValues } = useForm<FormValues>({
    defaultValues: { firstName: "", lastName: "", email: "" },
  });

  // 保存成功後にデフォルト値を現在の値に更新（dirty 状態をクリア）
  const onSubmit = async (data: FormValues) => {
    await saveUser(userId, data);
    // ユーザーが入力した値はそのままに、デフォルト値を更新
    resetDefaultValues(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("firstName")} />
      <input {...register("lastName")} />
      <input {...register("email")} />
      <button type="submit">保存</button>
    </form>
  );
}

keepDirty オプションで状態を保持

// デフォルト値は更新するが、dirty 状態は現在のまま保持
resetDefaultValues(newDefaults, { keepDirty: true });

subscribe との組み合わせ

const { subscribe, resetDefaultValues } = useForm({
  defaultValues: { name: "" },
});

// サブスクリプション内で resetDefaultValues は呼ばないこと（無限ループの原因）

重要なルール / 注意事項

• resetDefaultValues はユーザーの入力済み値を変更しない。デフォルト値の基準線のみを更新する。
• 呼び出し後、isDirty は新しいデフォルト値と現在の入力値の差分で再計算される。
• subscribe のコールバック内で呼び出すと無限ループになるため禁止。
• v7.77.0 以前は reset(values) でデフォルト値と入力値を同時に更新する必要があったが、resetDefaultValues により分離が可能になった。

Related

• reset
• resetField
• formState
• useForm

useForm — resetField

resetField メソッドは個別のフィールドの状態と値をリセットする。フォーム全体ではなく、特定のフィールドのみをリセットしたい場合に使用する。

シグネチャ

resetField: (name: string, options?: ResetFieldOptions) => void

引数

オプション

コード例

基本的なリセット

import { useForm } from "react-hook-form";

function App() {
  const { register, resetField, formState: { errors } } = useForm({
    defaultValues: { firstName: "", lastName: "" },
  });

  return (
    <form>
      <input {...register("firstName", { required: true })} />
      {errors.firstName && <span>必須です</span>}

      <button type="button" onClick={() => resetField("firstName")}>
        firstName をリセット
      </button>
    </form>
  );
}

エラーを保持してリセット

resetField("firstName", { keepError: true });

新しいデフォルト値でリセット

resetField("firstName", { defaultValue: "新しい名前" });

dirty 状態を保持してリセット

resetField("firstName", { keepDirty: true });

副作用

resetField を呼び出すと、以下のフォーム状態が自動的に再評価される:

• isValid — バリデーションが再実行され、フォームの有効性が再計算される。
• isDirty — フィールドのリセットにより、フォーム全体の dirty 状態が再計算される。

重要なルール / 注意事項

• フィールド名は register で登録されたものと完全一致する必要がある。一致しない場合、操作は暗黙的に失敗する。
• defaultValue オプションに undefined は渡せない。
• defaultValue を指定すると、そのフィールドの defaultValue 自体が更新される（以降の isDirty 比較に影響）。
• フォーム全体をリセットする場合は reset メソッドを使用すること。

useForm — setError

setError メソッドはフィールドに手動でエラーを設定する。サーバーサイドバリデーションの結果をフォームに反映する場合や、API エラーを表示する場合に使用する。

シグネチャ

setError: (
  name: string,
  error: { type: string; message?: string; types?: Record<string, string> },
  config?: { shouldFocus?: boolean }
) => void

引数

error オブジェクト

config オプション

コード例

基本的な使い方

import { useForm } from "react-hook-form";

function App() {
  const {
    register,
    handleSubmit,
    setError,
    formState: { errors },
  } = useForm();

  const onSubmit = async (data: any) => {
    const response = await fetch("/api/submit", {
      method: "POST",
      body: JSON.stringify(data),
    });

    if (!response.ok) {
      const result = await response.json();

      // サーバーから返されたフィールドエラーを設定
      if (result.errors?.email) {
        setError("email", {
          type: "server",
          message: result.errors.email,
        });
      }
    }
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("email")} />
      {errors.email && <span>{errors.email.message}</span>}
      <input type="submit" />
    </form>
  );
}

ルートエラー（サーバーエラー）

const onSubmit = async (data: any) => {
  try {
    await fetch("/api/submit", { method: "POST", body: JSON.stringify(data) });
  } catch {
    setError("root.serverError", {
      type: "400",
      message: "サーバーエラーが発生しました",
    });
  }
};

// エラー表示
{errors.root?.serverError && (
  <p>{errors.root.serverError.message}</p>
)}

複数エラー

setError("username", {
  types: {
    minLength: "3文字以上必要です",
    pattern: "英数字のみ使用可能です",
  },
});

フォーカス付きエラー設定

setError("email", {
  type: "manual",
  message: "このメールは既に登録されています",
}, { shouldFocus: true });

重要なルール / 注意事項

• register で設定されたバリデーションルールが通過する場合、setError で設定したエラーは永続化されない。例えば、minLength: 4 が満たされているフィールドに手動でエラーを設定しても、送信はブロックされない。
• 未登録フィールドに設定したエラーは、clearErrors で明示的にクリアするまで残る。
• setError は isValid を強制的に false にする。ただし最終的な有効性はスキーマや register のバリデーションルールに基づく。
• root エラーはフォーム送信をまたいで永続化されない。
• フィールド名に type や types を使用しないこと。エラーオブジェクトと競合する。
• handleSubmit のコールバック内で使用するのが一般的なパターン。

useForm — setFocus

setFocus メソッドは登録済みの input フィールドにプログラム的にフォーカスを設定する。初期フォーカスや特定操作後のフォーカス移動に使用する。

シグネチャ

setFocus: (name: string, options?: { shouldSelect?: boolean }) => void

引数

オプション

コード例

初期フォーカス

import { useEffect } from "react";
import { useForm } from "react-hook-form";

type FormValues = {
  firstName: string;
  lastName: string;
};

function App() {
  const { register, handleSubmit, setFocus } = useForm<FormValues>();

  useEffect(() => {
    setFocus("firstName");
  }, [setFocus]);

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input {...register("firstName")} placeholder="名" />
      <input {...register("lastName")} placeholder="姓" />
      <input type="submit" />
    </form>
  );
}

内容を選択してフォーカス

setFocus("firstName", { shouldSelect: true });

エラー時のフォーカス移動

const onError = (errors: FieldErrors) => {
  const firstErrorField = Object.keys(errors)[0];
  if (firstErrorField) {
    setFocus(firstErrorField as keyof FormValues);
  }
};

return <form onSubmit={handleSubmit(onSubmit, onError)}>...</form>;

ボタンクリックでフォーカス

<button type="button" onClick={() => setFocus("email")}>
  メール入力にフォーカス
</button>

重要なルール / 注意事項

• setFocus は register の ref を使用して focus() メソッドを呼び出す。フィールドが register で登録され、ref が正しく DOM に接続されている必要がある。
• reset の直後に setFocus を呼び出してはならない。reset は全入力の参照を削除するため、フォーカスが機能しない。
• カスタムコンポーネントを使用する場合は、ref が内部の input 要素に正しく転送されている必要がある。
• shouldFocusError オプション（useForm のオプション）を使用すると、バリデーション失敗時に自動的に最初のエラーフィールドにフォーカスされる。手動でのフォーカス制御が不要な場合はそちらを活用すること。

useForm — setValue

setValue メソッドは登録済みフィールドの値をプログラム的に設定する。バリデーションや dirty 状態の更新もオプションで制御可能。

シグネチャ

setValue: (
  name: string,
  value: unknown,
  config?: {
    shouldValidate?: boolean;
    shouldDirty?: boolean;
    shouldTouch?: boolean;
  }
) => void

引数

オプション

コード例

基本的な使い方

import { useForm } from "react-hook-form";

function App() {
  const { register, setValue, handleSubmit } = useForm({
    defaultValues: { firstName: "", lastName: "" },
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input {...register("firstName")} />
      <input {...register("lastName")} />

      <button type="button" onClick={() => setValue("firstName", "太郎")}>
        名前を設定
      </button>

      <input type="submit" />
    </form>
  );
}

バリデーション付き

setValue("firstName", "太郎", { shouldValidate: true });

dirty 状態の更新付き

setValue("firstName", "太郎", { shouldDirty: true });

複数オプション

setValue("firstName", "太郎", {
  shouldValidate: true,
  shouldDirty: true,
  shouldTouch: true,
});

ドット記法によるネストフィールド

// 推奨: ドット記法で個別指定
setValue("user.firstName", "太郎");
setValue("user.lastName", "山田");

// 非推奨: オブジェクトをまとめて渡す（パフォーマンスが低下する可能性）
setValue("user", { firstName: "太郎", lastName: "山田" });

依存フィールドの自動計算

const { watch, setValue, formState } = useForm();
const [a, b] = watch(["a", "b"]);

useEffect(() => {
  if (formState.touchedFields.a && formState.touchedFields.b) {
    setValue("c", `${a} ${b}`);
  }
}, [setValue, a, b, formState]);

重要なルール / 注意事項

• ドット記法でフィールドを個別に指定するのがパフォーマンス面で推奨される。ネストオブジェクトをまとめて渡すより効率的。
• フィールド配列を更新する場合は、setValue よりも useFieldArray の replace や update メソッドを使用することを推奨。
• 再レンダリングはエラーの修正/発生時、または dirty/touched 状態が変化した場合にのみ発生する。
• 未登録フィールドに setValue を使用しても新しいフィールドは作成されない。
• setValue を使用する前にフィールドを register で登録すること。
• value に undefined を渡すことはできない。

useForm — setValues

setValues メソッドは複数のフォームフィールドの値を一括で更新する。v7.74.0 以降で利用可能。個別フィールドを順番に setValue で更新するよりも効率的で、冗長な深いクローンをスキップしてパフォーマンスを向上させる。

バージョン要件

• v7.74.0+

シグネチャ

setValues: (
  value: Partial<TFieldValues> | ((current: TFieldValues) => Partial<TFieldValues>),
  options?: {
    shouldValidate?: boolean;
    shouldDirty?: boolean;
    shouldTouch?: boolean;
  }
) => void

引数

オプション

コード例

オブジェクトで一括設定

import { useForm } from "react-hook-form";

type FormValues = {
  firstName: string;
  lastName: string;
  email: string;
};

function App() {
  const { register, setValues } = useForm<FormValues>({
    defaultValues: { firstName: "", lastName: "", email: "" },
  });

  const fillForm = () => {
    setValues({
      firstName: "太郎",
      lastName: "山田",
      email: "taro@example.com",
    });
  };

  return (
    <form>
      <input {...register("firstName")} />
      <input {...register("lastName")} />
      <input {...register("email")} />
      <button type="button" onClick={fillForm}>
        フォームを埋める
      </button>
    </form>
  );
}

コールバック関数で更新

// 現在の値を元に一部のフィールドを更新
setValues((currentValues) => ({
  ...currentValues,
  firstName: "更新後の名前",
}));

バリデーション付きで設定

setValues(
  { firstName: "太郎", email: "taro@example.com" },
  { shouldValidate: true, shouldDirty: true }
);

重要なルール / 注意事項

• setValue の一括版として設計されており、複数フィールドを効率的に更新する。各フィールドで個別の setValue を呼ぶよりパフォーマンスが高い。
• undefined の値を含むフィールドは更新されない。
• フィールド配列の操作には useFieldArray の replace や update メソッドを使用すること。

Related

• setValue
• reset
• useForm

useForm — subscribe

subscribe メソッドは、コンポーネントの再レンダリングなしにフォーム状態の変更を購読する。外部システムとの連携やアナリティクスなど、UI 更新が不要な場面に適している。

シグネチャ

subscribe: (props: {
  name?: string[];
  formState?: Partial<ReadFormState>;
  callback: (state: FormState) => void;
  exact?: boolean;
}) => () => void

Props

戻り値

コード例

基本的な値の購読

import { useEffect } from "react";
import { useForm } from "react-hook-form";

function App() {
  const { register, subscribe } = useForm({
    defaultValues: { name: "", email: "" },
  });

  useEffect(() => {
    const unsubscribe = subscribe({
      formState: { values: true },
      callback: ({ values }) => {
        console.log("フォーム値が変更されました:", values);
      },
    });

    return () => unsubscribe();
  }, [subscribe]);

  return (
    <form>
      <input {...register("name")} />
      <input {...register("email")} />
    </form>
  );
}

特定フィールドの購読

useEffect(() => {
  const unsubscribe = subscribe({
    name: ["email"],
    formState: { values: true, errors: true },
    callback: ({ values, errors }) => {
      console.log("email:", values.email);
      if (errors.email) {
        console.log("エラー:", errors.email.message);
      }
    },
  });

  return () => unsubscribe();
}, [subscribe]);

バリデーション状態の購読

useEffect(() => {
  const unsubscribe = subscribe({
    formState: { isValid: true, isDirty: true },
    callback: ({ isValid, isDirty }) => {
      // 外部システムにフォーム状態を同期
      analytics.track("formState", { isValid, isDirty });
    },
  });

  return () => unsubscribe();
}, [subscribe]);

重要なルール / 注意事項

• コールバック内で setValue や reset などの状態変更メソッドを呼び出してはならない。無限ループの原因になる。
• 再レンダリングは発生しない。UI の更新が必要な場合は watch や useWatch を使用すること。
• メモリリーク防止のため、必ずクリーンアップ関数で unsubscribe を実行すること。
• watch のコールバック形式の代替として推奨される方法。

useForm — trigger

trigger メソッドはバリデーションを手動で実行する。フォーム全体、単一フィールド、または複数フィールドのバリデーションをプログラム的にトリガーできる。

シグネチャ

trigger: (
  name?: string | string[],
  options?: { shouldFocus?: boolean }
) => Promise<boolean>

引数

引数パターン

オプション

戻り値

コード例

全フィールドのバリデーション

import { useForm } from "react-hook-form";

function App() {
  const { register, trigger, formState: { errors } } = useForm();

  const validateAll = async () => {
    const isValid = await trigger();
    console.log("フォームは有効:", isValid);
  };

  return (
    <form>
      <input {...register("firstName", { required: true })} />
      <input {...register("email", { required: true })} />

      <button type="button" onClick={validateAll}>
        全バリデーション
      </button>
    </form>
  );
}

単一フィールドのバリデーション

const validateEmail = async () => {
  const isValid = await trigger("email");
  if (isValid) {
    console.log("メールアドレスは有効です");
  }
};

複数フィールドのバリデーション

const validateStep = async () => {
  const isValid = await trigger(["firstName", "lastName", "email"]);
  if (isValid) {
    // 次のステップに進む
    goToNextStep();
  }
};

ネストフィールドのバリデーション

await trigger("user.email");
await trigger("items.0.title");

フォーカス付きバリデーション

await trigger("email", { shouldFocus: true });

ウィザード形式フォームでの使用

function WizardForm() {
  const { register, trigger } = useForm();
  const [step, setStep] = useState(1);

  const nextStep = async () => {
    const fieldsToValidate =
      step === 1
        ? ["firstName", "lastName"]
        : ["email", "phone"];

    const isValid = await trigger(fieldsToValidate);
    if (isValid) {
      setStep((prev) => prev + 1);
    }
  };

  return (
    <form>
      {step === 1 && (
        <>
          <input {...register("firstName", { required: true })} />
          <input {...register("lastName", { required: true })} />
        </>
      )}
      {step === 2 && (
        <>
          <input {...register("email", { required: true })} />
          <input {...register("phone")} />
        </>
      )}
      <button type="button" onClick={nextStep}>
        次へ
      </button>
    </form>
  );
}

重要なルール / 注意事項

• 単一フィールド名（string）を指定した場合のみ、レンダリングの最適化が適用される。そのフィールドのみが再レンダリングされる。
• string[] または undefined を指定した場合は、formState 全体の再レンダリングがトリガーされる。
• 非同期バリデーションにも対応。Promise<boolean> が返されるため、await で結果を待機できる。
• shouldFocus オプションは register で ref が登録されている input にのみ機能する。

useForm — unregister

unregister メソッドは、登録済みの input フィールドの登録を解除し、対応するバリデーションルールと値を削除する。単一または複数のフィールドを一度に解除可能。

シグネチャ

unregister: (name: string | string[], options?: UnregisterOptions) => void

引数

オプション

コード例

基本的な使い方

import { useForm } from "react-hook-form";

function App() {
  const { register, unregister, handleSubmit } = useForm<{
    firstName: string;
    lastName: string;
  }>();

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input {...register("firstName")} />
      <input {...register("lastName")} />

      <button type="button" onClick={() => unregister("lastName")}>
        lastName を解除
      </button>

      <input type="submit" />
    </form>
  );
}

複数フィールドの解除

unregister(["firstName", "lastName"]);

オプション付き

unregister("lastName", {
  keepDirty: true,
  keepError: true,
});

重要なルール / 注意事項

• 組み込みバリデーションは削除される。register で設定したバリデーションルールは、登録解除と同時に無効になる。
• スキーマバリデーション（Yup, Zod など）は影響を受けない。スキーマ定義は登録解除後も残るため、スキーマ側も適宜調整する必要がある。
• 登録解除後は対応する input コンポーネントをアンマウントすること。アンマウントしない場合、register のコールバックが再度フィールドを登録してしまう。
• 動的フォームで条件付きフィールドを削除する場合に特に有用。

useForm — watch

watch メソッドは指定したフィールドの値の変更を監視し、条件付きレンダリングや値の表示に使用する。値が変更されると再レンダリングがトリガーされる。

シグネチャ（オーバーロード）

単一フィールド監視

watch(name: string, defaultValue?: unknown): unknown

複数フィールド監視

watch(names: string[], defaultValue?: Record<string, unknown>): unknown[]

全フィールド監視

watch(): Record<string, unknown>

コールバック監視（非推奨）

watch(
  callback: (data: Record<string, unknown>, info: { name?: string; type?: string }) => void,
  defaultValues?: Record<string, unknown>
): { unsubscribe: () => void }

コールバック形式は非推奨。代わりに subscribe() メソッドを使用すること。

引数

戻り値

コード例

単一フィールドの監視

const { register, watch } = useForm({ defaultValues: { name: "" } });
const nameValue = watch("name");

return (
  <div>
    <input {...register("name")} />
    <p>入力値: {nameValue}</p>
  </div>
);

複数フィールドの監視

const [firstName, lastName] = watch(["firstName", "lastName"]);

return (
  <p>
    フルネーム: {firstName} {lastName}
  </p>
);

条件付きレンダリング

const { register, watch } = useForm();
const showEmail = watch("hasEmail");

return (
  <form>
    <input type="checkbox" {...register("hasEmail")} />
    {showEmail && <input {...register("email")} />}
  </form>
);

全フィールドの監視

const formValues = watch();
console.log(formValues); // { firstName: "...", lastName: "...", ... }

重要なルール / 注意事項

• defaultValue を指定しない場合、register 前の初回レンダリングでは undefined が返される。useForm の defaultValues 指定を推奨。
• defaultValue と useForm の defaultValues の両方が設定されている場合、defaultValue が優先される。
• watch はルートレベルの再レンダリングをトリガーする。パフォーマンスが重要な場合は useWatch フックを検討すること。
• watch の結果はレンダリングフェーズ用に最適化されており、useEffect の依存配列には適さない。値の変更検知には外部の比較フックを使用すること。
• コールバック形式の watch は非推奨。代わりに subscribe() を使用すること。

useForm

useForm は React Hook Form の中核となるカスタムフックで、フォーム全体の管理を担う。オプションを受け取り、フォーム操作用のメソッド群を返す。

シグネチャ

useForm<TFieldValues extends FieldValues = FieldValues>(
  props?: UseFormProps<TFieldValues>
): UseFormReturn<TFieldValues>

オプション

戻り値

コード例

import { useForm } from "react-hook-form";

type FormValues = {
  firstName: string;
  lastName: string;
  email: string;
};

function App() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<FormValues>({
    mode: "onBlur",
    defaultValues: {
      firstName: "",
      lastName: "",
      email: "",
    },
  });

  const onSubmit = (data: FormValues) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("firstName", { required: true })} />
      {errors.firstName && <span>名前は必須です</span>}

      <input {...register("email", { pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ })} />
      {errors.email && <span>有効なメールアドレスを入力してください</span>}

      <input type="submit" />
    </form>
  );
}

非同期デフォルト値

const { register, handleSubmit } = useForm({
  defaultValues: async () => {
    const response = await fetch("/api/user");
    return await response.json();
  },
});

resolver（Zod）

import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

const schema = z.object({
  name: z.string().min(1, "名前は必須です"),
  age: z.number().min(18, "18歳以上である必要があります"),
});

const { register, handleSubmit } = useForm({
  resolver: zodResolver(schema),
});

重要なルール / 注意事項

• defaultValues に undefined を含めないこと。コントロールドコンポーネントのデフォルトと競合する。
• defaultValues はキャッシュされる。リセットするには reset API を使用する。
• shouldUnregister: true の場合、useEffect でのフォーム値購読はできない。
• resolver は { values: {}, errors: {} } の形式でオブジェクトを返す必要がある。
• mode: 'onChange' はパフォーマンスに影響するため、必要な場合のみ使用する。

useFormContext

深くネストされたコンポーネント構造で、props のバケツリレー（prop drilling）を避けるためのカスタムフック。FormProvider でラップされたコンポーネントツリー内で、フォームメソッドにアクセスできる。

シグネチャ

const methods = useFormContext<TFieldValues>(): UseFormReturn<TFieldValues>

前提条件

useFormContext を使用するには、親コンポーネントで FormProvider によるラップが必要。

Return

useForm が返す全てのメソッドとプロパティを返す。

コード例

基本的な使い方

import { useForm, FormProvider, useFormContext } from "react-hook-form";

// 親コンポーネント
function App() {
  const methods = useForm({
    defaultValues: { firstName: "", lastName: "" },
  });

  const onSubmit = (data) => console.log(data);

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        <NestedInput />
        <button type="submit">送信</button>
      </form>
    </FormProvider>
  );
}

// 子コンポーネント（深くネストされていても使用可能）
function NestedInput() {
  const { register } = useFormContext();
  return <input {...register("firstName")} />;
}

フォーム状態の利用

function SubmitButton() {
  const { formState: { isSubmitting, isValid } } = useFormContext();

  return (
    <button type="submit" disabled={isSubmitting || !isValid}>
      {isSubmitting ? "送信中..." : "送信"}
    </button>
  );
}

エラー表示

function ErrorDisplay({ name }) {
  const { formState: { errors } } = useFormContext();
  const error = errors[name];

  if (!error) return null;
  return <span role="alert">{error.message}</span>;
}

重要なルール

1. FormProvider が必須: useFormContext は FormProvider でラップされたコンポーネントツリー内でのみ動作する。ラップなしで使用すると undefined が返る。 2. useEffect の依存配列に `methods` 全体を入れない: methods オブジェクト全体を useEffect の依存配列に含めると、不要な再レンダリングや無限ループが発生する。必要な個別メソッド（例: reset）を依存配列に入れること。

// NG: methods 全体を依存配列に入れる
const methods = useFormContext();
useEffect(() => {
  // ...
}, [methods]); // 無限ループの原因

// OK: 個別メソッドを依存配列に入れる
const { reset } = useFormContext();
useEffect(() => {
  reset(data);
}, [reset, data]);

3. 型安全性: TypeScript で型パラメータを渡すことで、返されるメソッドに型が適用される。

const { register } = useFormContext<{ firstName: string; lastName: string }>();

dev-tools

React Hook Form — FAQs

パフォーマンス

React Hook Form は非制御コンポーネントベースで設計されている。register が ref をキャプチャし、Controller が再レンダリングスコープを管理する。これにより入力時の再レンダリングを最小化し、マウント速度を向上させる。

アクセシブルなエラー表示

<input
  {...register("name", { required: true })}
  aria-invalid={errors.name ? "true" : "false"}
/>
{errors.name && <span role="alert">This field is required</span>}

クラスコンポーネントとの互換性

React Hook Form はフックベースのため、クラスコンポーネントでは直接使用できない。関数コンポーネントでラップし、props 経由でデータを渡す。

フォームリセット方法

フォーム値の初期化

// 同期
useForm({ defaultValues: { firstName: "", lastName: "" } })

// 非同期
useForm({ defaultValues: async () => fetch("/api/user").then(res => res.json()) })

// リアクティブ更新（外部データソース）
useForm({ values: externalData, resetOptions: { keepDirtyValues: true } })

ref の共有

const { ref, ...rest } = register("test")

<input
  {...rest}
  ref={(e) => {
    ref(e)
    myCustomRef.current = e
  }}
/>

ref なしの登録

useEffect 内で手動登録し、setValue / setError で管理:

useEffect(() => {
  register("test")
}, [register])

<input onChange={(e) => setValue("test", e.target.value)} />

最初のキー入力で値が消える

value ではなく defaultValue を使用する。React Hook Form は非制御入力が前提。

React Hook Form vs Formik vs Redux Form

watch vs getValues vs state

条件付きレンダリングとデフォルト値

三項演算子で入力を切り替える場合、一意の key prop を設定して React にコンポーネントの変更を認識させる:

{isA ? <input key="a" {...register("a")} /> : <input key="b" {...register("b")} />}

モーダル / タブ内のフォーム

各モーダル/タブに個別のフォームを作成し、送信データをローカル/グローバル state にキャプチャ。最終的に結合して処理する。

Get Started

TypeScript