Get Started

The idea

Form validation is usually written twice: required and maxLength in the JSX, and a validation routine on the server. The two are edited separately, so sooner or later they disagree. This package keeps one place to write it and derives the rest.

• The schema is the only source. Attributes such as required, minLength and type="email", the message shown next to a field, and the validation on the server all come from it.
• The DOM holds the values. React state carries only the messages on screen, the server errors that are still current, the identity of each repeated row, one dirty flag, and the row counts that adding or removing a row is measured against. Values are never copied into state, so the form does not re-render on every keystroke.
• It works without JavaScript. The constraint attributes are in the HTML the server sends, so the browser validates on its own with scripts disabled or not yet loaded.
• The server decides. Some checks have no HTML attribute, so parseForm validates every submission against the same schema and answers with per-field errors and the submitted values.

Installation

Add @k8ordo/form and zod, which the schema is written in.

npm install @k8ordo/form zod

The peer dependencies are below. TypeScript and @types/react are needed only for the shipped type declarations.

zod or zod/mini

The conversion reads zod's shared core, so a schema written with either entry works, and nothing in the package notices which one you chose. Only the Server Component and the Server Action import the schema, so zod does not reach the browser either way. When the client imports the schema module too — a GET form with @k8ordo/state, for instance — zod/mini keeps that bundle small.

import * as z from 'zod';

export const talkSchema = z.object({
  title: z
    .string()
    .min(1, 'Enter a title')
    .max(120, 'Use 120 characters or fewer'),
});

import * as z from 'zod/mini';

export const talkSchema = z.object({
  title: z
    .string()
    .check(
      z.minLength(1, 'Enter a title'),
      z.maxLength(120, 'Use 120 characters or fewer'),
    ),
});

zod/mini bundles no locale, so its default message is Invalid input — unless the classic zod entry is also in use in the same process, which installs its English locale globally. The text next to a field is zod's own too, so either write the messages yourself or load a locale, as in z.config(z.locales.ja()).

The server/client split

There are two entry points. @k8ordo/form/server is the side that reads the schema; @k8ordo/form holds the hooks that run in the browser. A form is put together in three steps.

1. Call formFields(schema) in a Server Component or at its module scope. The result is plain JSON — attributes, messages, rules and the dropped report — with no functions and no zod.
2. Pass the result to a client component as a prop and hand it to useForm(fields, state). Being JSON, it crosses the RSC boundary, and zod stays out of the client bundle.
3. The Server Action receives the submission, and parseForm(schema, formData) returns either typed data or a state holding per-field errors.

The types of the formFields result and of the action state are exported from both entries, since the result shows up on the client as a prop.

A complete form

A form that registers a talk, in four files: the schema, the page, the Server Action and the form. The example is an @k8ordo/server application, which has Server Actions.

// src/routes/talks/new/_parts/talk-schema.ts
import * as z from 'zod';

export const talkSchema = z.object({
  title: z
    .string()
    .min(1, 'Enter a title')
    .max(120, 'Use 120 characters or fewer'),
  eventUrl: z.url('Enter the event URL'),
  minutes: z.coerce
    .number('Enter the length in minutes')
    .int('Use whole minutes')
    .min(5, 'A talk is at least 5 minutes'),
  recorded: z.boolean(),
});

// src/routes/talks/new/page.tsx
import { formFields } from '@k8ordo/form/server';

import { TalkForm } from './_parts/talk-form';
import { talkSchema } from './_parts/talk-schema';

const talkFields = formFields(talkSchema);

export default function NewTalkPage() {
  return <TalkForm fields={talkFields} />;
}

// src/routes/talks/new/_parts/actions.ts
'use server';

import { parseForm } from '@k8ordo/form/server';
import type { FormState } from '@k8ordo/form/server';
import { redirect } from '@k8ordo/server/runtime';

import { talkSchema } from './talk-schema';
import { insertTalk } from './talks.server';

export async function createTalk(
  _previous: FormState,
  formData: FormData,
): Promise<FormState> {
  const parsed = parseForm(talkSchema, formData);
  if (!parsed.success) return parsed.state;
  await insertTalk(parsed.data);
  redirect('/talks');
}

// src/routes/talks/new/_parts/talk-form.tsx
'use client';

import { useForm } from '@k8ordo/form';
import type { FormFields } from '@k8ordo/form';
import { useActionState } from 'react';

import { createTalk } from './actions';

type Props = {
  fields: FormFields<'title' | 'eventUrl' | 'minutes' | 'recorded', never>;
};

export function TalkForm({ fields }: Props) {
  const [state, formAction] = useActionState(createTalk, {});
  const form = useForm(fields, state);
  const title = form.field('title');
  const eventUrl = form.field('eventUrl');
  const minutes = form.field('minutes');
  const recorded = form.field('recorded');

  return (
    <form {...form.props} action={formAction}>
      <label>
        Title
        <input {...title.input} aria-invalid={title.invalid} />
      </label>
      {title.error !== undefined && <p>{title.error}</p>}

      <label>
        Event URL
        <input {...eventUrl.input} aria-invalid={eventUrl.invalid} />
      </label>
      {eventUrl.error !== undefined && <p>{eventUrl.error}</p>}

      <label>
        Minutes
        <input {...minutes.input} aria-invalid={minutes.invalid} />
      </label>
      {minutes.error !== undefined && <p>{minutes.error}</p>}

      <label>
        <input {...recorded.input} />
        Recorded
      </label>

      {state.formError !== undefined && <p>{state.formError}</p>}
      <button type="submit">Register</button>
    </form>
  );
}

// src/routes/talks/new/_parts/talk-form.tsx
'use client';

import type { formFields } from '@k8ordo/form/server';

import type { talkSchema } from './talk-schema';

type Props = {
  fields: ReturnType<typeof formFields<typeof talkSchema>>;
};

What happens on submit

• Without JavaScript, the browser validates against the constraint attributes and stops a submission that fails, in its own wording.
• With JavaScript, useForm sets noValidate on the form and shows zod's wording when a field is left. It does not block the submission; the submission goes to the Server Action.
• When parseForm reports a failure, each error appears next to its field, and focus moves to the first field listed in state.errors.

How a message appears and goes away, and what parseForm returns in detail, are on the Validation page.

Next steps

• Fields — the attributes each zod type derives; nested objects, repeated rows, checkbox groups and files
• Validation — how messages behave, what parseForm returns, cross-field rules and server-answered checks
• Patterns — multi-step forms, GET forms with @k8ordo/state, and pairing with @k8ordo/ui
• A live demo — the GET form on the @k8ordo/form landing page