forms

Sign-up pages, invoice editors and settings screens all need the same three things: check the input before it is sent, stop a second click while it saves, and show the server's "this customer does not exist" under the right field instead of in a generic alert. @kitr/forms gives you all three from one schema and one <Form> component.

It is React Hook Form re-exported unchanged, plus useSchemaForm (with a Standard Schema resolver), a <Form> that maps server errors onto fields, and headless, accessible field helpers. It runs in the browser; for the server half of a form see server actions or API routes.

The examples follow one form through the page: Ada creates invoices for Acme's customers in the app at app.acme.com.

Install

kitr add forms

Everything kitr add changes

What kitr add does:

• Installs @kitr/forms, react-hook-form, @hookform/resolvers and zod.
• Adds @kitr/forms to packages in kitrrc.ts.
• Adds a ## kitr: forms section to AGENTS.md that tells agents to build forms with useSchemaForm and <Form>, and that a KitrError with fieldErrors lands on fields while anything else goes to useRootError().

kitr add forms writes no config file and asks no questions. The app and fullstack kits include it, with the styled form component from Style fields.

What kitr remove does

In a server-only project kitr add skips forms with a warning, because it needs React. kitr remove forms removes the package from kitrrc.ts, uninstalls @kitr/forms, react-hook-form and @hookform/resolvers, and removes the AGENTS.md section. It leaves zod installed, because your server code usually uses it too.

Configure

@kitr/forms has no config file. Each form is set up where you write it, with useSchemaForm and <Form>:

// app/components/invoices/new-invoice-form.tsx
import { Form, useSchemaForm } from '@kitr/forms'
import { newInvoiceSchema } from '#app/validators/invoices'

export function NewInvoiceForm({ onCreate }: { onCreate: (values: unknown) => Promise<unknown> }) {
  const form = useSchemaForm(newInvoiceSchema, {
    mode: 'onTouched',
    defaultValues: { customerEmail: '', amount: '', dueOn: '' },
  })
  return (
    <Form form={form} onSubmit={onCreate} resetOnSuccess>
      {/* fields */}
    </Form>
  )
}

useSchemaForm(schema, options) takes every useForm option except resolver. The common ones:

<Form> takes these props. Any other prop goes on the <form> element.

Build your first form

Start with a schema in its own file, so the server can import the same one.

// app/validators/invoices.ts
import { z } from 'zod'

export const newInvoiceSchema = z.object({
  customerEmail: z.email('Enter the customer’s email'),
  amount: z.coerce.number().positive('Amount must be more than zero'),
  dueOn: z.iso.date('Pick a due date'),
})

export type NewInvoice = z.output<typeof newInvoiceSchema>

Then the form. Each field is a <FormField> with an input inside it.

// app/components/invoices/new-invoice-form.tsx
import { FieldInput, Form, FormField, SubmitButton, useRootError, useSchemaForm } from '@kitr/forms'
import { type NewInvoice, newInvoiceSchema } from '#app/validators/invoices'

export function NewInvoiceForm({ onCreate }: { onCreate: (invoice: NewInvoice) => Promise<unknown> }) {
  const form = useSchemaForm(newInvoiceSchema, {
    defaultValues: { customerEmail: '', amount: '', dueOn: '' },
  })

  return (
    <Form form={form} onSubmit={onCreate} resetOnSuccess aria-label="New invoice">
      <FormField name="customerEmail" label="Customer email">
        <FieldInput type="email" autoComplete="off" />
      </FormField>
      <FormField name="amount" label="Amount (USD)">
        <FieldInput inputMode="decimal" />
      </FormField>
      <FormField name="dueOn" label="Due on" description="Customers see this date on the invoice.">
        <FieldInput type="date" />
      </FormField>
      <RootError />
      <SubmitButton pendingText="Creating…">Create invoice</SubmitButton>
    </Form>
  )
}

function RootError() {
  const error = useRootError()
  return error ? <p role="alert">{error}</p> : null
}

Render it from a route and give it something to do on submit:

// app/routes.ts
import { NewInvoiceForm } from '#app/components/invoices/new-invoice-form'

r.page('/invoices/new', {
    <NewInvoiceForm onCreate={async (invoice) => console.log('created', invoice)} />
  ),
  lazy: () => import('./pages/invoices/new'),
})

// app/pages/invoices/new.tsx
export default () => (

Open /invoices/new, tab out of the empty email field and "Enter the customer’s email" appears under it. Fill the form with [email protected], 120 and a date, press the button, and the console prints:

created { customerEmail: '[email protected]', amount: 120, dueOn: '2026-12-01' }

amount arrives as the number 120 because onSubmit receives the schema's output. While onCreate runs, the button reads "Creating…" and is disabled; when it resolves, resetOnSuccess clears the form.

Validate with any schema library

useSchemaForm accepts any Standard Schema: zod, valibot or arktype.

// app/components/invoices/new-invoice-form.tsx
import * as v from 'valibot'
import { useSchemaForm } from '@kitr/forms'

const newInvoiceSchema = v.object({
  customerEmail: v.pipe(v.string(), v.email('Enter the customer’s email')),
  amount: v.pipe(v.string(), v.transform(Number), v.minValue(0.01, 'Amount must be more than zero')),
  dueOn: v.pipe(v.string(), v.isoDate('Pick a due date')),
})

export function useNewInvoiceForm() {
  return useSchemaForm(newInvoiceSchema, {
    defaultValues: { customerEmail: '', amount: '', dueOn: '' },
  })
}

The schema's input type is what the fields hold (amount is a string); its output type is what onSubmit receives (amount is a number). Both are inferred, so form.setValue('amount', 120) is a type error and values.amount.toFixed(2) in onSubmit is not. Async checks such as .refine(async ...) work too.

Choose when fields are validated

useSchemaForm defaults to mode: 'onTouched': a field is checked when it first loses focus, then on every change until it passes.

// app/components/invoices/quick-invoice-form.tsx
import { useSchemaForm } from '@kitr/forms'
import { newInvoiceSchema } from '#app/validators/invoices'

export function useQuickInvoiceForm() {
  return useSchemaForm(newInvoiceSchema, {
    mode: 'onSubmit',
    reValidateMode: 'onBlur',
    defaultValues: { customerEmail: '', amount: '', dueOn: '' },
  })
}

Submitting always validates every field, whatever the mode.

Submit to your API

onSubmit can return any promise. To update the query cache as well, pass a query mutation's mutateAsync. Here it posts to an external API through http:

// app/queries/invoices.ts
import { mutationFrom, queryFrom } from '@kitr/query'
import { httpMutation, httpQuery } from '@kitr/http'
import { app } from '#app/app'
import type { NewInvoice } from './schema'

const http = () => app.container.use('http')

export const invoiceQuery = queryFrom(
  httpQuery<string, NewInvoice & { id: string }>(http, {
    key: (id) => ['invoices', 'detail', id],
    path: (id) => `invoices/${id}`,
  }),
)

export const createInvoice = mutationFrom(
  httpMutation<NewInvoice, { id: string; number: string }>(http, {
    path: 'invoices',
    effects: { invalidate: [['invoices', 'list']] },
  }),
)

// app/routes.ts
r.page('/invoices/new', { lazy: () => import('./pages/invoices/new') })

// app/pages/invoices/new.tsx
import { useMutation } from '@kitr/query'
import { useNavigate } from '@kitr/router'
import { NewInvoiceForm } from '#app/components/invoices/new-invoice-form'
import { createInvoice } from '#app/queries/invoices'

export default function NewInvoicePage() {
  const create = useMutation(createInvoice)
  const navigate = useNavigate()
  return (
    <NewInvoiceForm
      onCreate={async (invoice) => {
        const created = await create.mutateAsync(invoice)
        await navigate({ to: '/invoices/$id', params: { id: created.id } })
      }}
    />
  )
}

Submit to a server action

In a project with server actions, the action validates with the same schema on the server:

// app/actions/invoices/create_invoice.ts
import { defineMutation } from '@kitr/actions'
import { newInvoiceSchema } from '#app/validators/invoices'

export const createInvoice = defineMutation('invoices.create', {
  input: newInvoiceSchema,
  effects: { invalidate: [['invoices', 'list']] },
  handler: async ({ input }) => {
    // save the invoice
    return { id: 'inv_1042', number: 'ACME-1042', ...input }
  },
})

// app/pages/invoices/new.tsx
import { useMutation } from '@kitr/query'
import { NewInvoiceForm } from '#app/components/invoices/new-invoice-form'

export default function NewInvoicePage() {
  const create = useMutation('invoices.create')
  return <NewInvoiceForm onCreate={(invoice) => create.mutateAsync(invoice)} />
}

useMutation('invoices.create') finds the mutation by its defineMutation name; kitr types types it. If someone bypasses the browser check, the action rejects with VALIDATION and the same messages land under the same fields.

Show server errors on fields

When onSubmit throws or rejects, <Form> reads the KitrError's fieldErrors: each key is a field path, each value a list of messages, and the first shows under the field:

// what the server sent back (HTTP 422)
{
  code: 'VALIDATION',
  message: 'Validation failed',
  status: 422,
  fieldErrors: {
    customerEmail: ['No customer with this email'],
    'lines.0.quantity': ['Only 3 left in stock'],
    _root: ['Invoices are locked while the month closes'],
  },
}

The rules:

• A key whose first segment is a field in the form (customerEmail, or lines for lines.0.quantity) goes on that field.
• _root, and any key the form does not have (plan, billing.vatId when there is no billing field), goes to the root error, which useRootError() returns.
• An error without fieldErrors (a CONFLICT, a NETWORK failure, a 500) puts its message on the root error.
• Only the first message per field is shown.

API routes and server actions answer failed validation with fieldErrors already, and http converts common backend formats.

Throw field errors from the server

For a rule the schema cannot check, such as "this customer exists", throw KitrError.validation with the field it belongs to:

// app/actions/invoices/create_invoice.ts
import { defineMutation } from '@kitr/actions'
import { KitrError } from '@kitr/kitr/app'
import { newInvoiceSchema } from '#app/validators/invoices'

const customers = new Set(['[email protected]', '[email protected]'])

export const createInvoice = defineMutation('invoices.create', {
  input: newInvoiceSchema,
  handler: async ({ input }) => {
    if (!customers.has(input.customerEmail)) {
      throw KitrError.validation({ customerEmail: ['No customer with this email'] })
    }
    return { id: 'inv_1042', number: 'ACME-1042', ...input }
  },
})

Ada sees "No customer with this email" under the email field. A message for the whole form goes under _root:

throw KitrError.validation({ _root: ['Invoices are locked while the month closes'] })

Nested fields use dot paths: 'billing.vatId' or 'lines.2.quantity'.

Show a form-level error

useRootError() returns the message of errors that are not about one field, or undefined. Call it inside <Form>:

// app/components/invoices/form-alert.tsx
import { useRootError } from '@kitr/forms'

export function FormAlert() {
  const error = useRootError()
  if (!error) return null
  return (
    <p role="alert" className="rounded-md border border-destructive/40 p-3 text-destructive">
      {error}
    </p>
  )
}

The root error clears on each submit. A dropped connection shows "Network request failed"; a 500 in production shows "Internal server error" and keeps the real message in the server log.

Show a pending state

<SubmitButton> is a type="submit" button that is disabled and has aria-busy="true" while onSubmit runs. pendingText replaces its label in that time:

<SubmitButton pendingText="Creating…" className="btn-primary">
  Create invoice
</SubmitButton>

A disabled prop you pass is combined with the pending state. For anything else that reacts to the submit, call useFormStatus() inside <Form>:

// app/components/invoices/cancel-link.tsx
import { useFormStatus } from '@kitr/forms'
import { Link } from '@kitr/router'

export function CancelLink() {
  const { pending, isValid } = useFormStatus()
  return (
    <Link to="/invoices" disabled={pending} data-ready={isValid || undefined}>
      Cancel
    </Link>
  )
}

pending is true while onSubmit runs; isValid is React Hook Form's formState.isValid.

Run code after a submit

onSuccess runs with what onSubmit returned and the submitted values. onError runs after the error is on the fields, with a KitrError. Neither runs when the browser-side schema check fails.

// app/components/invoices/new-invoice-panel.tsx
import { toast } from '@kitr/toast'
import { Form, useSchemaForm } from '@kitr/forms'
import { newInvoiceSchema } from '#app/validators/invoices'

export function NewInvoicePanel({ onCreate }: { onCreate: (v: unknown) => Promise<{ number: string }> }) {
  const form = useSchemaForm(newInvoiceSchema, {
    defaultValues: { customerEmail: '', amount: '', dueOn: '' },
  })
  return (
    <Form
      form={form}
      onSubmit={onCreate}
      onSuccess={(invoice) => toast.success(`Invoice ${(invoice as { number: string }).number} created`)}
      onError={(error) => {
        if (error.code !== 'VALIDATION') toast.error(error.message)
      }}
      resetOnSuccess
    >
      {/* fields */}
    </Form>
  )
}

Edit an existing record

Load the record first and render the form only once it is there, passing it as defaultValues. Leave resetOnSuccess off for edit forms:

// app/routes.ts
r.page('/invoices/$id/edit', { lazy: () => import('./pages/invoices/edit') })

// app/pages/invoices/edit.tsx
import { FieldInput, Form, FormField, SubmitButton, useSchemaForm } from '@kitr/forms'
import { useSuspenseQuery } from '@kitr/query'
import { getRouteApi } from '@kitr/router'
import { newInvoiceSchema } from '#app/validators/invoices'
import { invoiceQuery } from '#app/queries/invoices'

const route = getRouteApi('/invoices/$id/edit')

export default function EditInvoicePage() {
  const { id } = route.useParams()
  const { data: invoice } = useSuspenseQuery(invoiceQuery.options(id))
  const form = useSchemaForm(newInvoiceSchema, {
    defaultValues: {
      customerEmail: invoice.customerEmail,
      amount: String(invoice.amount),
      dueOn: invoice.dueOn,
    },
  })
  return (
    <Form form={form} onSubmit={(values) => console.log('save', id, values)}>
      <FormField name="dueOn" label="Due on">
        <FieldInput type="date" />
      </FormField>
      <SubmitButton>Save</SubmitButton>
    </Form>
  )
}

To follow data that changes while the form is open, pass values instead of defaultValues; the form resets each time values changes. form.formState.isDirty tells you whether Ada changed anything.

Use your own inputs

<FieldInput> is a plain <input>. For a <select>, a <textarea> or a styled input, call useFieldProps() inside <FormField> and spread the result:

// app/components/invoices/currency-select.tsx
import { useFieldProps } from '@kitr/forms'

export function CurrencySelect() {
  const props = useFieldProps()
  // => { id, 'aria-invalid', 'aria-describedby', name, onChange, onBlur, ref }
  return (
    <select {...props}>
      <option value="USD">US dollar</option>
      <option value="EUR">Euro</option>
    </select>
  )
}

<FormField name="currency" label="Currency">
  <CurrencySelect />
</FormField>

useFieldProps() returns the field's id, aria-invalid and aria-describedby, plus everything form.register(name) returns. A checkbox works the same way and arrives as a boolean:

<FormField name="sendNow" label="Email the invoice to the customer now">
  <FieldInput type="checkbox" />
</FormField>

Lay out a field yourself

<FormField> renders the label, children, description, then error. To place things differently, pass a function as its child; it receives { id, name, invalid, describedBy }. Call form.register there rather than useFieldProps():

// app/components/invoices/note-field.tsx
import { FormField, useFormContext } from '@kitr/forms'

export function NoteField() {
  const form = useFormContext<{ note: string }>()
  return (
    <FormField name="note" label="Note to the customer" description="Up to 500 characters.">
      {({ id, invalid, describedBy }) => (
        <textarea
          id={id}
          rows={4}
          aria-invalid={invalid || undefined}
          aria-describedby={describedBy || undefined}
          {...form.register('note')}
        />
      )}
    </FormField>
  )
}

Wrap a controlled component

Date pickers, comboboxes and rich-text editors often take value and onChange but no ref. Use React Hook Form's Controller, exported from @kitr/forms:

// app/components/invoices/due-date-field.tsx
import { Controller, FormField, useFormContext } from '@kitr/forms'
import { DatePicker } from '#components/date-picker'

export function DueDateField() {
  const form = useFormContext<{ dueOn: string }>()
  return (
    <FormField name="dueOn" label="Due on">
      {({ id, describedBy }) => (
        <Controller
          control={form.control}
          name="dueOn"
          render={({ field }) => (
            <DatePicker id={id} aria-describedby={describedBy} value={field.value} onChange={field.onChange} />
          )}
        />
      )}
    </FormField>
  )
}

Field and server errors still appear, because they are keyed by name.

Repeat fields

Invoice lines are a list. useFieldArray adds and removes rows; each row's fields use an index path:

// app/components/invoices/invoice-lines.tsx
import { FieldInput, FormField, useFieldArray, useFormContext } from '@kitr/forms'

type Lines = { lines: { description: string; quantity: string }[] }

export function InvoiceLines() {
  const form = useFormContext<Lines>()
  const lines = useFieldArray({ control: form.control, name: 'lines' })
  return (
    <fieldset>
      <legend>Lines</legend>
      {lines.fields.map((line, index) => (
        <div key={line.id}>
          <FormField name={`lines.${index}.description`} label="Description">
            <FieldInput />
          </FormField>
          <FormField name={`lines.${index}.quantity`} label="Quantity">
            <FieldInput inputMode="numeric" />
          </FormField>
          <button type="button" onClick={() => lines.remove(index)}>
            Remove
          </button>
        </div>
      ))}
      <button type="button" onClick={() => lines.append({ description: '', quantity: '1' })}>
        Add line
      </button>
    </fieldset>
  )
}

Use line.id as the key, not index. A server error for lines.1.quantity lands under the second row's input.

Watch a field

To show or hide part of the form based on a value, read it with form.watch:

// app/components/invoices/delivery-fields.tsx
import { FieldInput, FormField, useFormContext } from '@kitr/forms'

export function DeliveryFields() {
  const form = useFormContext<{ sendNow: boolean; ccEmail: string }>()
  const sendNow = form.watch('sendNow')
  if (!sendNow) return null
  return (
    <FormField name="ccEmail" label="Copy to" description="Grace in finance gets a copy.">
      <FieldInput type="email" />
    </FormField>
  )
}

The component re-renders when sendNow changes. Make a hidden field optional in the schema, or use a zod discriminatedUnion.

Submit without the Form component

When a submit does not go through <Form>, such as a "Mark as paid" button, call applyServerErrors yourself. It puts the error on the form as <Form> does and returns true for a VALIDATION error:

// app/components/invoices/mark-paid.tsx
import { applyServerErrors, useForm } from '@kitr/forms'

export function MarkPaid({ save }: { save: (paidOn: string) => Promise<void> }) {
  const form = useForm({ defaultValues: { paidOn: '' } })
  const onClick = async () => {
    try {
      await save(form.getValues('paidOn'))
    } catch (error) {
      const isValidation = applyServerErrors(form, error)
      // => true for KitrError.validation(...), false for anything else
      if (!isValidation) console.error(error)
    }
  }
  return (
    <>
      <input type="date" {...form.register('paidOn')} />
      <button type="button" onClick={onClick}>Mark as paid</button>
      <p role="alert">{form.formState.errors.paidOn?.message}</p>
    </>
  )
}

It accepts a KitrError, the JSON shape a server sent, or any thrown value; anything that is not a field error ends up on root.server.

Style fields

The components are headless. <FormField> marks its parts with data-kitr attributes so you can style them from CSS or with Tailwind arbitrary variants:

<FormField
  name="amount"
  label="Amount (USD)"
  className="grid gap-1.5 [&_[data-kitr=field-error]]:text-sm [&_[data-kitr=field-error]]:text-destructive"
>
  <FieldInput />
</FormField>

For a finished look, copy the styled components into your app:

kitr ui add form

This writes app/components/ui/form.tsx (plus button, input and label if missing), exporting Form, FormField, FieldInput, FormMessage (the root error) and SubmitButton. Import from #components/ui/form instead of @kitr/forms; the file is yours to edit.

Make forms accessible

<FormField> and useFieldProps() produce this markup for a field with a description and a failed check:

<div data-kitr="field" data-invalid="">
  <label for="_r_2_" data-kitr="label">Due on</label>
  <input id="_r_2_" aria-describedby="_r_2_-description _r_2_-error" type="date" name="dueOn" aria-invalid="true">
  <p id="_r_2_-description" data-kitr="description">Customers see this date on the invoice.</p>
  <p id="_r_2_-error" role="alert" data-kitr="field-error">Pick a due date</p>
</div>

• Clicking the label focuses the input, because the ids match.
• A screen reader reads the description and the error with the input, through aria-describedby.
• The error is announced when it appears, through role="alert".
• <Form> sets noValidate on the <form>, so the browser's own bubbles never compete with these messages.

Give the <form> an accessible name (aria-label="New invoice") when the page has more than one.

Commands

kitr make:form invoice

writes:

// app/components/forms/invoice-form.tsx
import { useSchemaForm } from '@kitr/forms'
import { z } from 'zod'
import { FieldInput, Form, FormField, FormMessage, SubmitButton } from '#components/ui/form'

export const invoiceSchema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
})
export type InvoiceValues = z.infer<typeof invoiceSchema>

export function InvoiceForm({ defaultValues, onSubmit }: { defaultValues?: Partial<InvoiceValues>; onSubmit: (values: InvoiceValues) => Promise<unknown> }) {
  const form = useSchemaForm(invoiceSchema, { defaultValues: { name: '', ...defaultValues } })
  return (
    <Form form={form} onSubmit={onSubmit} className="grid gap-4">
      <FormMessage />
      <FormField name="name" label="Name">
        <FieldInput autoComplete="off" />
      </FormField>
      <SubmitButton>Save</SubmitButton>
    </Form>
  )
}

Errors

These are the KitrError codes a form shows and where each appears.

Testing

Forms run in a DOM test without an app, router or server. Render, type, submit; to test server errors, make the submit function reject with the error the server would send.

// app/components/invoices/new-invoice-form.test.tsx
import { fireEvent, render, screen, waitFor } from '@testing-library/react'
import { KitrError } from '@kitr/kitr/app'
import { describe, expect, it, vi } from 'vitest'
import { NewInvoiceForm } from './new-invoice-form'

function fill(email: string, amount: string, dueOn: string) {
  fireEvent.change(screen.getByLabelText('Customer email'), { target: { value: email } })
  fireEvent.change(screen.getByLabelText('Amount (USD)'), { target: { value: amount } })
  fireEvent.change(screen.getByLabelText('Due on'), { target: { value: dueOn } })
  fireEvent.submit(screen.getByRole('form', { name: 'New invoice' }))
}

describe('NewInvoiceForm', () => {
  it('shows schema errors without calling the server', async () => {
    const onCreate = vi.fn()
    render(<NewInvoiceForm onCreate={onCreate} />)
    fill('grace', '0', '')
    expect(await screen.findByText('Enter the customer’s email')).toBeTruthy()
    expect(screen.getByText('Amount must be more than zero')).toBeTruthy()
    expect(screen.getByLabelText('Customer email').getAttribute('aria-invalid')).toBe('true')
    expect(onCreate).not.toHaveBeenCalled()
  })

  it('submits typed values and resets', async () => {
    const onCreate = vi.fn().mockResolvedValue({ id: 'inv_1042' })
    render(<NewInvoiceForm onCreate={onCreate} />)
    fill('[email protected]', '120', '2026-12-01')
    await waitFor(() =>
      expect(onCreate).toHaveBeenCalledWith({
        customerEmail: '[email protected]',
        amount: 120,
        dueOn: '2026-12-01',
      }),
    )
    await waitFor(() =>
      expect((screen.getByLabelText('Customer email') as HTMLInputElement).value).toBe(''),
    )
  })

  it('puts server errors under the right field and the rest at the top', async () => {
    const onCreate = vi
      .fn()
      .mockRejectedValueOnce(KitrError.validation({ customerEmail: ['No customer with this email'] }))
      .mockRejectedValueOnce(new KitrError('CONFLICT', 'Invoice ACME-1042 already exists'))
    render(<NewInvoiceForm onCreate={onCreate} />)
    fill('[email protected]', '80', '2026-12-01')
    expect(await screen.findByText('No customer with this email')).toBeTruthy()
    fireEvent.submit(screen.getByRole('form', { name: 'New invoice' }))
    expect(await screen.findByText('Invoice ACME-1042 already exists')).toBeTruthy()
  })
})

A form that calls useMutation needs the query client: render it with renderWithKitr from testing.

Next steps