@k8ordo/form

Get Started

Build a talk submission form: write one zod schema, then derive the input attributes and the server-side validation from it.

On this page

Install

bash
npm install @k8ordo/form zod

It runs with:

  • React 19.3 or later
  • TypeScript 7 or later, when you write TypeScript

The guide for AI agents ships at node_modules/@k8ordo/form/docs/GUIDE.md. Point your AGENTS.md or the like at that path.

formFields and parseForm read the schema on the server, and useForm runs in a Client Component.

Information

Note

A schema written with zod/mini works the same way. If client code imports the schema module too, choose zod/mini for the smaller bundle.

Defining the schema

src/lib/schema.ts
import * 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),
});

Describe the form’s fields and their constraints in a zod schema. The wording passed to min or url is what the error shows.

A form submits every value as a string, numbers included. Declare a number field with z.coerce.number() so the string is converted before it is checked.

Input attributes

src/routes/talks/new/page.tsx
import { 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);
Built once, at module scope

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

Hand the schema to formFields in a Server Component. It builds the attributes for each input, such as required and maxlength, along with the error messages.

The result is plain JSON, so it can go to a Client Component as props. zod stays out of the browser bundle.

Validating the submission

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'));
}

A Server Action receives the submission and hands the same schema and the formData to parseForm.

When it passes, parsed.data holds the typed values. When it fails, return parsed.state. The errors and the values the user entered go back to the form, and focus moves to the first field with an error.

After saving, move on with redirect() from @k8ordo/framework/server. See Server Actions.

Rendering the form

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);
The derived fields and the state the Server Action returned
  const title = form.field('title');
  const eventUrl = form.field('eventUrl');
  const minutes = form.field('minutes');

  return (
    <form {...form.props} action={formAction}>
Spread onto the `<form>` only
      <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>
  );
}

Pass the Server Action to useActionState. Then pass the state it returns and the fields prop to useForm.

Spread form.props onto the <form>, and each field’s input onto its control. The error is in error; show it right next to the control.

The typed values are not kept in React state, so typing never re-renders the form. There is no per-field registration either.

Playground

Talk form demo

The form built above. With nowhere to send it, it stops once the values are valid.

Try it

  1. Press “Submit” with nothing filled in. Focus moves to the first field, and each field’s error appears.
  2. Type example into “Event URL” and leave the field. “Enter the event URL” appears.
  3. Type 90 into “Length (minutes)” and leave the field. “Make it 60 minutes or less” appears.
k8ordo

React libraries that use Baseline features without holding back.