フォーム処理パターン
このガイドでは、React Hook FormとZodを使用した型安全なフォームとバリデーションの構築方法を説明します。これらのパターンはAPIに送信する前にデータの整合性を確保し、ユーザーに明確なフィードバックを提供します。
このガイドを使用するタイミング
以下が必要な場合にこのガイドを使用してください:
- エンティティ(製品、ユーザー、注文)の作成・編集用フォームを構築する
- APIに送信する前にユーザー入力を検証する
- フィールドレベルのエラーメッセージをユーザーに表示する
- 動的フィールド(注文アイテム、タグ)を持つ複雑なフォームを処理する
- 他のフォーム値に基づいて 条件付きフィールドを表示する
このパターンが解決する問題
| 問題 | 解決策 |
|---|---|
| 無効なデータがAPIに送信される | Zodが送信前に検証する |
| フォームとAPIの型が一致しない | ZodスキーマからTypeScript型を推論する |
| キー入力ごとにフォームが再レンダリングされる | React Hook Formは非制御入力を使用する |
| バリデーションエラーを表示しにくい | フィールドごとの自動エラー状態 |
| 動的フィールドの管理が複雑 | useFieldArrayが追加/削除を処理する |
技術スタック
| ライブラリ | 目的 |
|---|---|
| React Hook Form | フォーム状態管理 |
| Zod | スキーマバリデーション |
| @hookform/resolvers | Zod統合 |
| shadcn/ui Form | フォームUIコンポーネント |
インストール
npm install react-hook-form zod @hookform/resolvers
フォームコンポーネントアーキテクチャ
フォームシステムは階層化されたコンポーネントアーキテクチャを使用します:
| コンポーネント | 役割 |
|---|---|
Form | フォーム全体をラップするコンテキストプロバイダー(react-hook-formのFormProviderを使用) |
FormField | Controllerを使用してフィールドをフォーム状態に接続 |
FormItem | 単一フォームフィールドのコンテナ(ラベル、入力、エラー) |
FormLabel | フィールドに自動接続し、エラー状態を表示するラベル |
FormControl | フォームフィールドのpropsを入力要素に渡す |
FormMessage | バリデーションエラーメッセージを表示 |
FormDescription | フィールドのオプションヘルプテキスト |