はじめる
登壇の申し込みフォームを例に、zodのスキーマを1つ書き、入力欄の属性とサーバーでの検証をそこから作ります。
このページの内容
インストール
npm install @k8ordo/form zod次の環境で動きます。
- React 19.3以上
- TypeScriptで書くなら、TypeScript 7以上
エージェント向けのガイドはnode_modules/@k8ordo/form/docs/GUIDE.mdに入っています。AGENTS.mdなどからこのパスを参照させてください。
スキーマを読むformFieldsとparseFormはサーバーで動き、useFormはClient Componentで動きます。
メモ
スキーマはzod/miniで書いても同じように動きます。クライアントのコードもスキーマのモジュールをimportするなら、バンドルの小さいzod/miniを選んでください。
スキーマの定義
src/lib/schema.tsimport * as z from 'zod';
export const talkSchema = z.object({
title: z.string().min(1, 'Enter a title').max(120),
eventUrl: z.url('Enter the event URL'),
minutes: z.coerce.number().int().min(5).max(60),
});フォームの入力欄と、それぞれの制約をzodのスキーマに書きます。minやurlに渡した文言は、そのままエラーの表示に使われます。
フォームは数値の入力欄の値も文字列として送ります。数値の入力欄はz.coerce.number()で定義し、文字列を数値に変換してから検証します。
入力欄の属性
src/routes/talks/new/page.tsximport { formFields } from '@k8ordo/form/server';
import { TalkForm } from '../../../components/talk-form';
import { createTalk } from '../../../lib/actions';
import { talkSchema } from '../../../lib/schema';
const talkFields = formFields(talkSchema);
モジュールスコープで1回だけ作る
export default function NewTalkPage() {
return <TalkForm action={createTalk} fields={talkFields} />;
}Server ComponentでformFieldsにスキーマを渡します。入力欄に付けるrequiredやmaxlengthなどの属性と、エラーの文言が作られます。
戻り値はJSONなので、propsとしてClient Componentに渡せます。zodはブラウザのバンドルに入りません。
送信の検証
src/lib/actions.ts'use server';
import { parseForm } from '@k8ordo/form/server';
import type { FormState } from '@k8ordo/form/server';
import { href } from '@k8ordo/framework';
import { redirect } from '@k8ordo/framework/server';
import { talkSchema } from './schema';
import { saveTalk } from './talks.server';
export async function createTalk(
_prev: FormState,
formData: FormData,
) {
const parsed = parseForm(talkSchema, formData);
if (!parsed.success) return parsed.state;
await saveTalk(parsed.data);
redirect(href('/talks'));
}送信はServer Actionで受け取り、parseFormに同じスキーマとformDataを渡します。
検証に通ると、parsed.dataに型の付いた値が入ります。通らないときはparsed.stateを返します。エラーと入力した値がフォームに戻り、最初にエラーになった入力欄にフォーカスが移ります。
保存のあとの移動は@k8ordo/framework/serverのredirect()で行います。詳しくはServer Actionを見てください。
フォームの描画
src/components/talk-form.tsx'use client';
import { useForm } from '@k8ordo/form';
import type { FormFields, FormState } from '@k8ordo/form';
import { useActionState } from 'react';
type Props = {
action: (prev: FormState, formData: FormData) => Promise<FormState>;
fields: FormFields<'title' | 'eventUrl' | 'minutes', never>;
};
export function TalkForm({ action, fields }: Props) {
const [state, formAction] = useActionState(action, {});
const form = useForm(fields, state);
入力欄の属性と、Server Actionが返したstate
const title = form.field('title');
const eventUrl = form.field('eventUrl');
const minutes = form.field('minutes');
return (
<form {...form.props} action={formAction}>
`<form>`にだけ展開する
<label>
Title <input {...title.input} />
</label>
{title.error !== undefined && <p>{title.error}</p>}
<label>
Event URL <input {...eventUrl.input} />
</label>
{eventUrl.error !== undefined && <p>{eventUrl.error}</p>}
<label>
Length (minutes) <input {...minutes.input} />
</label>
{minutes.error !== undefined && <p>{minutes.error}</p>}
<button type="submit">Submit</button>
</form>
);
}useActionStateにServer Actionを渡します。返ってくるstateと、propsのfieldsをuseFormに渡します。
form.propsは<form>に、各欄のinputは対応する入力欄に展開します。エラーはerrorに入るので、入力欄のすぐ近くに表示します。
入力した値はReactのstateで管理しないので、キーを押すたびに再描画されることはありません。入力欄を1つずつ登録する手順もありません。
申し込みのデモ
ここまでで作ったフォームです。送信先が無いので、送信できる値になった時点で止まります。
試してみる
- 何も入力せずに「申し込む」を押します。最初の欄にフォーカスが移り、エラーが表示されます。
- 「イベントのURL」に
exampleと入力して欄から離れます。「イベントのURLを入力してください」と表示されます。 - 「長さ(分)」に
90と入力して欄から離れます。「60分以下にしてください」と表示されます。