mcpField
T
tanstack-form

tanstack-form

github.com/oakoss開発21207 回インストール11 週間前に更新
リポジトリ

tanstack-form について

TanStack Form は、独自の UI コンポーネントでフォームを構築する開発者向けのヘッドレス状態管理ツールです。検証、状態、送信を管理し、動的フィールドや非同期チェック、再利用可能なフォームパターンにも対応します。

主な機能

  1. 01ヘッドレスなフォーム状態管理
  2. 02同期・非同期バリデーション
  3. 03連動フィールドのバリデーション
  4. 04動的な配列フィールド
  5. 05再利用可能なフォームとフィールドグループ
  6. 06Standard Schema 対応

活用シーン

  1. 01カスタム入力を使った複数ステップフォームの構築
  2. 02サーバー応答に基づくフィールド検証
  3. 03依存関係のあるフィールドを含むフォームの作成
  4. 04動的なフォームフィールド一覧の管理

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/oakoss/agent-skills --skill tanstack-form

インストール後、Claude Code で/tanstack-formを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
advanced-patterns.md
array-fields.md
basic-patterns.md
form-composition.md
react-aria-integration.md
schema-validation.md
server-integration.md
shadcn-integration.md
validation.md

詳細

TanStack Form

概要

TanStack Form は ヘッドレスのフォーム状態管理ツールであり、UI コンポーネントライブラリではありません。入力要素を独自に用意し、そのイベントを処理します。TanStack Form はバリデーション、状態、送信ロジックを管理します。

使用する場面： 複雑な複数ステップのフォーム、再利用可能なフォームパターン、動的なフィールド配列、フィールド間のバリデーション、非同期のサーバーバリデーション、細かなパフォーマンス最適化が必要なフォーム。

使用しない場面： ネイティブ HTML バリデーションを使うシンプルなフォーム（通常のフォーム要素を使用してください）、サーバー側のみでバリデーションする場合（Server Actions を使用してください）、バリデーションが不要な静的なフォーム。

React Compiler： TanStack Form はまだ React Compiler と互換性がありません。TanStack Form API を使用するファイルまたはコンポーネントでは、React Compiler を無効にしてください。

クイックリファレンス

パターンAPI主なポイント
基本的なフォームuseForm({ defaultValues, onSubmit })Field コンポーネントを備えたフォームインスタンス
フィールドform.Field with name and children render fnレンダープロパティパターンで完全に制御
フィールドのバリデーションvalidators: { onChange, onBlur, onSubmit }同期バリデーション。エラー文字列または undef を返します
非同期バリデーションonChangeAsync, onChangeAsyncDebounceMsデバウンス付きのサーバーチェック
連動するフィールドonChangeListenTo: ['fieldName']依存先が変更されたときに再バリデーション
フォームの送信form.handleSubmit()バリデーションを行い、有効な場合に onSubmit を呼び出します
フォームの状態form.state.values, isSubmitting, isValidフォーム全体の状態にアクセス
フィールドの状態field.state.value, meta.errors, meta.isTouchedフィールドごとの状態にアクセス
配列フィールドmode="array", pushValue, removeValueヘルパーを使った動的なリスト
Standard SchemaZod/Valibot/ArkType/Yup スキーマを直接渡すネイティブ対応のため、アダプターは不要
フォームの合成createFormHook({ fieldComponents })コンテキストを使った再利用可能なフィールド
大きなフォームの分割withForm({ defaultValues, render })型安全なフォームセクション用の HOC
再利用可能なフィールドグループwithFieldGroup({ defaultValues, render })バリデーションロジックを共有するフィールドグループ
状態の購読form.Subscribe with selector効率的に再レンダリングを制御
フィールドエラーの表示meta.isTouched && meta.errors.lengthユーザー操作後にエラーを表示
フォームレベルのバリデーション{ fields } を返す validators.onSubmitフォームレベルから特定のフィールドにエラーを設定
フォームのリセットform.reset()defaultValues にリセット

よくある間違い

間違い正しいパターン
e.target.value を直接使用する適切に状態を管理するには field.handleChange(value) を使用する
onBlur={field.handleBlur} がないバリデーションのタイミングと touched 状態のため、必ず追加する
エラーをすぐに表示するfield.state.meta.isTouched && errors.length を確認する
非同期バリデーションのデバウンスを指定しないサーバーへの過剰なリクエストを避けるため、onChangeAsyncDebounceMs を設定する
バリデーションに listeners を使用する再バリデーションにはバリデーターで onChangeListenTo を使用する
送信時のみバリデーションするUX を向上させるため、onChange または onBlur バリデーターを追加する
フォームの送信を適切に処理しないデフォルトの動作を防止して form.handleSubmit() を呼び出す
QueryClient スタイルのインスタンスを作成するコンポーネントで useForm フックを直接使用する
バリデーター関数をインラインで記述する安定した参照として切り出すか、useCallback でラップする
配列フィールドでフィールド名がないネストしたフィールドにはテンプレート構文 hobbies[${index}].name を使用する
非同期バリデーターを await しないPromise を直接返すと、Form が await を処理する
送信前に isValidating を確認する代わりに canSubmit 状態セレクターを使用する

委任

  • フォームパターンの調査：既存のフォーム実装を探すには Explore エージェントを使用します
  • バリデーションスキーマの設計：複雑なフィールド間バリデーションロジックには Task エージェントを使用します
  • コードレビュー：フォームのバリデーション範囲の確認を code-reviewer エージェントに委任します

shadcn-ui スキルが利用可能な場合は、コンポーネントのスタイリングと構成を委任します。利用できない場合は、npx skills add oakoss/agent-skills --skill shadcn-ui を推奨します。

tanstack-query スキルが利用可能な場合は、キャッシュ管理とミューテーションパターンを委任します。 tanstack-start スキルが利用可能な場合は、サーバー関数とサーバー側のフォーム送信を委任します。 tanstack-router スキルが利用可能な場合は、送信後のナビゲーションとルートパターンを委任します。 tanstack-devtools スキルが利用可能な場合は、フォーム状態のデバッグを委任します。

参考資料

コメント

Markdown 対応