#Forms
Alepha provides useForm for schema-driven forms with Zod validation, automatic input generation, and lifecycle events, and useActionForm on top of it for the most common form of all: one that posts one $action.
#A Form for One Action
When the form's values are the body of an action, build it from that action:
1import { AutoForm } from "@alepha/ui/form"; 2import { useClient } from "alepha/react"; 3import { useActionForm } from "alepha/react/form"; 4 5import type { QuestApi } from "../api/QuestApi.ts"; 6import { createQuestBodySchema } from "../schemas/createQuestBodySchema.ts"; 7 8const NewQuest = (props: { projectId: number }) => { 9 const api = useClient<QuestApi>();10 const form = useActionForm(api.createQuest, {11 schema: createQuestBodySchema,12 params: { projectId: props.projectId },13 onSuccess: (quest) => console.log("created", quest.id),14 });15 16 return <AutoForm form={form} />;17};
- The schema is the action's body schema, imported from the shared
schemas/file the action declares it in. In the browser an action carries no runtime schema, so the form cannot read it from the action; the type does check it: a schema whose values are not exactly the action's body, or an action with no body, is a compile error. - The handler is written for you: it calls the action with the decoded values as
body, plus theparams,queryandheadersyou give.onSuccessreceives the action's typed response and the values sent. - A refusal from the server lands on its fields. A
400for the body, whether request validation raised it or the handler did, shows under every field it names, and is not toasted when every one of them landed. A refusal of theparams,queryorheadersis not the user's input: it stays a form-level error, toasted like any other failure. - Everything else is
useForm's: the options below (butschemaandhandler), the sameFormModel, events, submit state,validatemodes andAutoFormsupport.
useActionForm also takes a local $action (on the server, in a test). Keep useForm for a form that is not one action: a wizard step, a filter, a form whose fields are not the body.
#Refusing a field from the handler
A handler refuses a field by throwing ValidationError with the part of the request and the failing fields. It is the same 400 request validation sends, so the form treats both alike:
1import { $action, ValidationError } from "alepha/server"; 2 3class UserApi { 4 register = $action({ 5 method: "POST", 6 schema: { body: registerBodySchema, response: userSchema }, 7 handler: async ({ body }) => { 8 if (await this.users.emailTaken(body.email)) { 9 throw new ValidationError({10 part: "body",11 issues: [{ path: "/email", message: "Email already in use" }],12 });13 }14 return this.users.create(body);15 },16 });17}
Each issue's path is a JSON pointer into the body (/email, /address/city, /items/0/name). On the wire a ValidationError carries data.part ("params", "query", "headers" or "body") and data.issues ({ path, message } only), alone or inside a batched call. A SchemaValidationError thrown from a handler is not a refusal: it means the handler's own data broke a schema, and answers a 500.
#Basic Usage
1import { z } from "alepha"; 2import { useForm } from "alepha/react/form"; 3 4const LoginForm = () => { 5 const form = useForm({ 6 schema: z.object({ 7 email: z.email(), 8 password: z.text(), 9 }),10 handler: async (values) => {11 await api.login(values);12 },13 });14 15 return (16 <form {...form.props}>17 <input {...form.input.email.props} />18 <input {...form.input.password.props} type="password" />19 <button type="submit">Login</button>20 </form>21 );22}
Spread form.props on the <form> element and form.input.<field>.props on each input. The props include name, type, onChange, required, defaultValue, and other attributes derived from the schema.
#useForm Options
| Option | Type | Description |
|---|---|---|
schema |
ZObject |
Zod schema defining fields and validation. |
handler |
(values) => unknown |
Called on submit with validated values. |
initialValues |
Partial<Infer<T>> |
Pre-populate fields with existing data. |
keepDirty |
boolean (default true) |
When initialValues changes (a refetch after a save), keep the fields the user edited instead of overwriting them. |
validate |
"submit" | "blur" | "change" |
When a field is checked against the schema (default "submit"). See When Fields Are Checked. |
id |
string |
Prefix for field IDs and data-testid attributes. |
onChange |
(key, value, store) => void |
Called on every field change. |
onError |
(error) => void |
Called when submission throws an error. Marks the error handled, so ActionErrorToaster does not toast it. |
onReset |
() => void |
Called when the form is reset. |
onCreateField |
(name, schema) => InputHTMLAttributes |
Customize generated input attributes. |
The second argument to useForm is a dependency array (defaults to []). When dependencies change, the form is re-created. To switch the form to another record (editing A, then B), put the record id in the dependencies rather than swapping initialValues. The latest handler, beforeSubmit, validate, onError, onChange, onReset and onCreateField are always used, so a handler may close over render state.
#FormModel
useForm returns a FormModel<T> instance with the following API:
#form.props
Spread on the <form> element. Includes:
id: unique form identifiernoValidate: set totrue(validation is handled by the schema)method:"post", so a submit that happens before hydration (slow bundle, Enter in a text field) never serialises the fields, a password included, into the URLonSubmit: callsform.submit()withpreventDefaultonReset: callsform.reset()
#form.input
A proxy object where each key corresponds to a schema property. Each field has:
| Property | Type | Description |
|---|---|---|
props |
InputHTMLAttributes |
Spread on the <input> element. |
path |
string |
JSON pointer path (e.g., /email). |
required |
boolean |
Whether the field is required. |
schema |
ZType |
The Zod schema for this field. |
set |
(value: any) => void |
Programmatically set the field value. |
blur |
() => void |
Tell the form focus left the field (validate: "blur"). props.onBlur calls it. |
initialValue |
any |
The field's initial value (from initialValues or schema defaults). |
items |
Record<string, InputField> |
Child fields, for object-typed properties - see Nested Object Fields. |
form |
FormModel |
Reference back to the parent form. |
#form.submit()
Triggers form submission programmatically. Coerces the input strings to the schema's types and validates them, then calls the handler with the decoded values. A second submit while one is in flight is ignored.
#form.reset(event)
Restores the form to its initial values (empty if no initialValues were given) and emits a form:reset event.
#form.errors
The error shown under each field, by JSON pointer: { "/email": "Email already in use" }. A failed submit fills it with every issue whose path names a field of the schema, the form's own schema refusal and a server 400 alike; an issue for the root ("") or for a path naming no field stays the form-level error. A field's entry clears when that field changes (an array row on its own, not its siblings), and every entry clears on reset and when a new submit begins. form:errors:changed fires on each change.
form.setErrors(issues) replaces them by hand and returns true when every issue named a field; form.clearErrors(path?) removes one field's (and those under it) or all.
#form.currentValues
Returns the current form values as a restructured object (nested keys like address.city become { address: { city: ... } }).
#Submission state
To react to an in-progress submission (e.g. disable the submit button), use the useFormState hook:
1const { loading } = useFormState(form, ["loading"]);
#Automatic Type Detection
Input types are automatically inferred from the schema:
| Schema Type | Input Type |
|---|---|
z.integer() |
number |
z.number() |
number |
z.boolean() |
checkbox |
z.text() |
text |
Field named password |
password |
Field named email |
email |
Field named url |
url |
z.date() |
date |
z.dateRange() |
range picker (@alepha/ui Control only) |
z.time() |
time |
z.datetime() |
datetime-local |
z.binary() |
file |
Note that email/password/url are detected from the field name, not the schema - a z.email() schema on a field named contact renders as plain text.
String constraints like maxLength and minLength are also applied to the input attributes.
#Nested Object Fields
For schemas with nested objects, use items to access child fields:
1const form = useForm({ 2 schema: z.object({ 3 address: z.object({ 4 street: z.text(), 5 city: z.text(), 6 }), 7 }), 8 handler: async (values) => { /* values.address.street, values.address.city */ }, 9});10 11// Access nested fields:12<input {...form.input.address.items.street.props} />13<input {...form.input.address.items.city.props} />
#Tracking Form State
Use useFormState to reactively track loading, dirty, error, and value states:
1import { useFormState } from "alepha/react/form"; 2 3const MyForm = () => { 4 const form = useForm({ /* ... */ }); 5 const { loading, dirty, error } = useFormState(form); 6 7 return ( 8 <form {...form.props}> 9 {/* inputs */}10 {error && <p>{error.message}</p>}11 <button type="submit" disabled={loading || !dirty}>12 {loading ? "Saving..." : "Save"}13 </button>14 </form>15 );16}
useFormState options:
The first argument is the form model (or { form, path } to track a specific field). The second argument is an array of keys to track, ["loading", "dirty", "error"] by default (values is only tracked when asked for):
1// Track only loading and error2const { loading, error } = useFormState(form, ["loading", "error"]);3 4// Track a specific field's error5const { error } = useFormState({ form, path: "/email" }, ["error"]);6 7// Track current values8const { values } = useFormState(form, ["values"]);
Return type:
| Property | Type | Description |
|---|---|---|
loading |
boolean |
True during form submission. |
dirty |
boolean |
True after any field change. Resets on reset, and on a successful submit when the form then holds what was sent or its baseline: an edit made while the submit was in flight keeps it dirty, a value the handler wrote back does not. |
error |
Error | undefined |
With the form: the last failed submit's error. With { form, path }: that field's entry of form.errors, as a FormValidationError. |
values |
Record | undefined |
Current form values (updated on change and submit). |
#When Fields Are Checked
By default the schema is checked when the form is submitted. validate checks a field sooner:
1const form = useForm({ schema, handler, validate: "blur" });
"submit"(default): on submit only."blur": also when focus leaves the field. EveryControlreports it, pickers included; a raw<input {...props} />does throughprops.onBlur."change": also on every change.
Blur and change decode the whole form and show only the touched field's issues, so an object-level .refine() (a "confirm password" match) lands on the field it names. Zod runs an object's refinements once its own fields pass, so such an error appears when the rest of the form is valid. Once a submit was refused, a field showing an error is rechecked on every change whatever the mode, so the error leaves as soon as it is fixed.
#Reading Values
useForm keeps values in the model, not in React state, so typing does not re-render the form. Subscribe only where a component needs them:
useFieldValue(form.input.email)returns[value, setValue]for one field and re-renders on that field only.useFormValues(form)returns every current value and re-renders on every change. Keep it for live previews and debug panels.<FormState form={form}>{({ loading, dirty }) => ...}</FormState>is a render-prop wrapper arounduseFormState.
useFormQuerySync(form, { keys: ["status", "q"] }) mirrors the listed fields to the URL query (?status=new&q=foo) and back, so a filter form survives a reload, a shared link and back/forward. It replaces the history entry rather than pushing one, and leaves query params it does not own alone.
All four are exported from alepha/react/form.
#With @alepha/ui
Raw <input {...props}> is the bare layer. In an application using @alepha/ui, render each field with Control from @alepha/ui/form, which picks the widget from the schema (select, date, date range, number, switch, upload, ...) and shows the label, description and field error. Flags force a variant (<Control input={form.input.status} select />). AutoForm renders a whole form from the schema.
1import { Control } from "@alepha/ui/form";2 3<form {...form.props}>4 <Control input={form.input.email} />5 <Control input={form.input.role} select />6</form>;
Control shows its field's error from form.errors, so several show at once, and a field mounted after the failure (an array row, a collapsed object opened later) shows its own. After a refused submit, AutoForm scrolls to the first invalid field and focuses it, opening a collapsed object to reach it, and its error popover lists every issue.
A picker with local state is still a form: make it a one-field useForm (initialValues for what the server says, onChange to save on change) rather than a hand-built control.
#Form Events
Forms emit events on the Alepha event system:
| Event | Payload | Description |
|---|---|---|
form:changed |
{ id, path, value, initial? } |
A field value changed (initial: true marks programmatic resets). |
form:reset |
{ id } |
Form was reset. |
form:submit:begin |
{ id } |
Submission started. |
form:submit:success |
{ id, values } |
Submission succeeded. |
form:submit:error |
{ id, error } |
Submission failed. |
form:submit:end |
{ id } |
Submission finished (always). |
form:errors:changed |
{ id, errors } |
form.errors changed; errors is the whole new map. |
Forms also emit react:action:begin, react:action:success, react:action:error, and react:action:end events with type: "form", so global action handlers apply to form submissions too.
The react:action:error of a form carries handled: true in three cases, and @alepha/ui's ActionErrorToaster does not toast it: the form was given an onError, the error is a FormValidationError whose every path names a field of the schema, so its message is already shown under that field, or it is a server ValidationError whose every issue useActionForm placed under a field. Any other failure still toasts: a FormValidationError with no path, one whose path names no field the form can show (a key of a z.record, a union variant, a key the schema does not have), and a 400 naming a field the form does not have.
#FormValidationError
Throw a FormValidationError in a useForm handler to report field-level errors the browser finds itself (with useActionForm, the server's ValidationError does this for you):
1import { FormValidationError } from "alepha/react/form"; 2 3handler: async (values) => { 4 const exists = await api.checkEmail(values.email); 5 if (exists) { 6 throw new FormValidationError({ 7 message: "Email already in use", 8 path: "/email", 9 });10 }11};
The path is a JSON pointer matching the field path (e.g., /email, /address/city). The message is shown under that field and not as a toast: the error is marked handled (see Form Events). To refuse several fields at once, pass issues: [{ path, message }, ...] as well; each lands on its field.
The form's own schema refuses input the same way: a required field left empty or a value out of range fails with a FormValidationError too, before the handler runs. So a react:action:error listener can tell a person's input from a fault by the error alone: a FormValidationError is a refusal, while a SchemaValidationError thrown from inside the handler (a response that broke its own schema, say) is left as it is. The @alepha/lore browser sigil relies on that, and does not report a refusal as a crash.