useActionStateとuseFormStatus

useActionState(action, initialState)は、Server Actionをラップして送信間でその状態を追跡するReact 19のフックです。Action関数と初期状態の値を受け取り、フォーム全体の動作を制御するために使えるタプルを返します。

このフックは[state, formAction, isPending]を返します。stateにはActionの直近の戻り値が保持され、初期状態はnullまたは指定した初期値になります。formActionはフォームに渡すラップ済みのActionです。isPendingは、Actionがサーバー上で実行されている間trueになります。

フォームを送信するたびにServer Actionが実行され、その戻り値が新しいstateになります。初回レンダーでは、stateはinitialStateと等しくなります。これにより、過去に送信したことがあるかどうかや、送信結果に応じてUIを簡単に切り替えられます。

Server Actionが{ errors: { email: 'Invalid email' } }を返す場合、インラインでエラーを表示できます：{state.errors?.email && <p>{state.errors.email}</p>}。状態は再レンダー後も保持されるため、次の送信が成功して状態を置き換えるまでエラーメッセージが表示され続けます。

Actionが{ success: true }を返すと、コンポーネントは成功メッセージをレンダーできます：{state?.success && <p>Form submitted!</p>}。状態の値に基づいて、フォームを条件付きで非表示にしたり、成功メッセージに置き換えたりできます。

useFormStatus()は、最も近い祖先の<form>要素が持つ保留状態を読み取るフックです。{ pending: boolean }を含むオブジェクトを返します。このフックはフォームの子であるコンポーネント内で使用する必要があり、フォーム自体をレンダーするコンポーネント内では使用できません。

useFormStatusをフォーム内で使用する必要があるのは、このフックがその上にあるReactツリーからフォームのコンテキストを読み取るためです。フォームをレンダーする同じコンポーネント内で呼び出すと、フォームの子孫ではなくフォームの兄弟要素になるため、フォームの状態にアクセスできません。

標準的なパターンは、送信ボタンを独自のコンポーネントとして切り出すことです：function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>Submit</button>; }。このコンポーネントをフォーム内に配置することで、フォームの保留状態にアクセスできるようになります。

送信ボタンにdisabled={pending}を設定すると、二重送信を防止できます。ユーザーが送信ボタンをクリックしてServer Actionが実行されている間、pendingはtrueになり、ボタンは無効化されてクリックできなくなります。Actionが完了するとpendingはfalseに戻り、ボタンが再び有効になります。

完全なフォームUXパターンでは、2つのフックを組み合わせます。フォームコンポーネント内のuseActionStateでActionの結果を追跡し、formActionを提供します。一方、子のSubmitButtonコンポーネント内のuseFormStatusで保留状態を追跡します。これらを組み合わせることで、バリデーションエラーの表示と、応答性の高い送信ボタンを実現できます。

さらに応答性の高い操作感を実現するには、useOptimisticをuseActionStateと組み合わせます。サーバーからの応答を待たず、期待される結果でUIをすぐに更新し、実際の応答が届いたら状態を整合させます。このパターンは、いいねボタン、todoリスト、その他の即時フィードバックが必要な操作でよく使われます。

useFormStatusが正しく動作するには、どこで呼び出す必要がありますか。

useActionState(action, initialState)は、Server Actionの結果を追跡するために[state, formAction, isPending]を返します。stateにはActionの戻り値が保持され、インラインでのエラーや成功メッセージの表示に利用できます。useFormStatus()はフォームの子コンポーネント内で{ pending }を提供し、応答性の高い送信ボタンを実現します。両方のフックを組み合わせることで、完全でアクセシブルなフォーム操作を構築できます。