Forms
Submit forms to API routes or shared capabilities, show field errors, and provide a retry form for visitors without JavaScript.
On this page
This recipe builds a contact form that posts to an API route, shows field errors, and keeps working with JavaScript disabled.
1. Write the API route
Validate on the server and return a Response:
import type { ApiRouteArgs } from "@pracht/core";
export async function POST({ request }: ApiRouteArgs) {
const form = await request.formData();
const name = String(form.get("name") ?? "").trim();
const email = String(form.get("email") ?? "").trim();
const message = String(form.get("message") ?? "").trim();
const errors: Record<string, string> = {};
if (!name) errors.name = "Name is required";
if (!email || !email.includes("@")) errors.email = "Valid email is required";
if (!message) errors.message = "Message is required";
if (Object.keys(errors).length > 0) {
return Response.json({ ok: false, errors, values: { name, email, message } }, { status: 400 });
}
await sendContactEmail({ name, email, message });
return Response.json({ ok: true, sent: true });
}Return the submitted values with the errors so the user does not lose their input.
2. Render the form
import { Form } from "@pracht/core";
import { useState } from "preact/hooks";
interface ContactResult {
ok: boolean;
sent?: boolean;
errors?: Record<string, string>;
values?: { name?: string; email?: string; message?: string };
}
export function Component() {
const [result, setResult] = useState<ContactResult | null>(null);
if (result?.sent) {
return <p class="success">Thanks! We'll be in touch.</p>;
}
const errors = result?.errors ?? {};
const values = result?.values ?? {};
return (
<div>
<h1>Contact Us</h1>
<Form
method="post"
action="/api/contact"
onResponse={async (response) => setResult(await response.json())}
>
<label>
Name
<input type="text" name="name" value={values.name} />
{errors.name && <span class="field-error">{errors.name}</span>}
</label>
<label>
Email
<input type="email" name="email" value={values.email} />
{errors.email && <span class="field-error">{errors.email}</span>}
</label>
<label>
Message
<textarea name="message">{values.message}</textarea>
{errors.message && <span class="field-error">{errors.message}</span>}
</label>
<button type="submit">Send</button>
</Form>
</div>
);
}Submit an empty form: the page does not reload, and each field shows its error. What happens on submit:
<Form>intercepts the submit event and sends the fields withfetch.- The API route validates and returns a
Response. - A 3xx response navigates the client router to its target and reloads that route's data. Any other response goes to
onResponseas a rawResponse; read the body withawait response.json(). - While the request is in flight,
useNavigation()reports the submission.
Without JavaScript, the browser performs a native form POST and navigates to the response, so this JSON handler shows a page of raw JSON. Step 3 fixes that.
3. Work without JavaScript
Answer a document post with a redirect. Enhanced submissions carry the x-pracht-capability-form header, so the handler can tell the two apart:
import { redirect, type ApiRouteArgs } from "@pracht/core";
export async function POST({ request }: ApiRouteArgs) {
const form = await request.formData();
const name = String(form.get("name") ?? "").trim();
const email = String(form.get("email") ?? "").trim();
const message = String(form.get("message") ?? "").trim();
const enhanced = request.headers.get("x-pracht-capability-form") !== null;
const errors: Record<string, string> = {};
if (!name) errors.name = "Name is required";
if (!email || !email.includes("@")) errors.email = "Valid email is required";
if (!message) errors.message = "Message is required";
if (Object.keys(errors).length > 0) {
if (enhanced) {
return Response.json({ ok: false, errors, values: { name, email, message } }, {
status: 400,
});
}
// No JS to render the errors, so hand them and the input back through
// the URL and let the route's loader put them on the page.
const query = new URLSearchParams({ invalid: Object.keys(errors).join(","), name, email });
return redirect(`/contact?${query}`, { request });
}
await sendContactEmail({ name, email, message });
return enhanced ? Response.json({ ok: true, sent: true }) : redirect("/contact?sent=1", {
request,
});
}Read the outcome in the contact route's loader from url.searchParams, and fall back to it when no enhanced result is in state:
import { Form, type LoaderArgs, type RouteComponentProps } from "@pracht/core";
import { useState } from "preact/hooks";
const MESSAGES: Record<string, string> = {
name: "Name is required",
email: "Valid email is required",
message: "Message is required",
};
interface ContactResult {
ok: boolean;
sent?: boolean;
errors?: Record<string, string>;
values?: { name?: string; email?: string; message?: string };
}
export function loader({ url }: LoaderArgs) {
const query = url.searchParams;
const invalid = (query.get("invalid") ?? "").split(",").filter((field) => field in MESSAGES);
return {
sent: query.has("sent"),
errors: Object.fromEntries(invalid.map((field) => [field, MESSAGES[field]])),
values: { name: query.get("name") ?? "", email: query.get("email") ?? "" },
};
}
export function Component({ data }: RouteComponentProps<typeof loader>) {
const [result, setResult] = useState<ContactResult | null>(null);
if (result?.sent ?? data.sent) {
return <p class="success">Thanks! We'll be in touch.</p>;
}
const errors = result?.errors ?? data.errors;
const values: ContactResult["values"] = result?.values ?? data.values;
return (
<Form method="post" action="/api/contact" onResponse={async (r) => setResult(await r.json())}>
<label>
Name <input type="text" name="name" value={values?.name} />
{errors.name && <span class="field-error">{errors.name}</span>}
</label>
<label>
Email <input type="email" name="email" value={values?.email} />
{errors.email && <span class="field-error">{errors.email}</span>}
</label>
<label>
Message <textarea name="message">{values?.message}</textarea>
{errors.message && <span class="field-error">{errors.message}</span>}
</label>
<button type="submit">Send</button>
</Form>
);
}Register /contact with render: "ssr" so the loader sees each request's query string. Disable JavaScript and submit a form with only a name: the page reloads at /contact with an error under email and message, and the name field keeps what you typed. A valid message lands on /contact?sent=1 and shows the thank-you text. The message body stays out of the URL because query strings end up in browser history and server logs.
If you do not need the no-JS path, keep the JSON-only handler from step 1.
Refresh loader data after a mutation
A JSON response does not reload the current route's data. Call useRevalidate() after a mutation that changes what the page shows:
import { useRevalidate } from "@pracht/core";
import type { RouteComponentProps } from "@pracht/core";
export function Component({ data }: RouteComponentProps<typeof loader>) {
const revalidate = useRevalidate();
async function handleAddTodo(text: string) {
const res = await fetch("/api/todos", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ text }),
});
if (res.ok) {
revalidate(); // Re-runs this route's loader
}
}
return (
<div>
<ul>{data.todos.map(t => <li key={t.id}>{t.text}</li>)}</ul>
<button onClick={() => handleAddTodo("New task")}>Add</button>
</div>
);
}The same pattern covers submissions from code rather than a form element, such as a delete button calling fetch().
Multiple actions on one page
Give each mutation its own API route:
<Form method="post" action="/api/settings/profile">
<input name="name" value={data.user.name} />
<button type="submit">Save Profile</button>
</Form>
<Form method="post" action="/api/settings/password">
<input type="password" name="current" placeholder="Current password" />
<input type="password" name="next" placeholder="New password" />
<button type="submit">Change Password</button>
</Form>Or post every form to one route and branch on a hidden intent field:
import { redirect, type ApiRouteArgs } from "@pracht/core";
export async function POST({ request }: ApiRouteArgs) {
const form = await request.formData();
const intent = form.get("intent");
switch (intent) {
case "update-profile": {
const name = String(form.get("name"));
await db.users.update({ name });
return Response.json({ ok: true });
}
case "change-password": {
const current = String(form.get("current"));
const next = String(form.get("next"));
// validate and update...
return Response.json({ ok: true, passwordChanged: true });
}
case "delete-account": {
await db.users.delete();
return redirect("/", { request });
}
default:
return Response.json({ ok: false, error: "Unknown intent" }, { status: 400 });
}
}Share one validation contract
Pass any Standard Schema to <Form schema> for client-side feedback: an invalid submission is not sent, and onValidationIssues receives the issues. Pass the same object to defineApi({ body }) so the server stays authoritative.
If the validator also implements Standard JSON Schema (Zod 4 does), it can be the input of a pracht capability too, so the form, API route, and agent tool share one contract. See Capabilities.
Client-side validation is feedback, not a security boundary. Always validate on the server.
File uploads
Set enctype="multipart/form-data" and read the file from formData():
<Form method="post" action="/api/avatar" enctype="multipart/form-data">
<input type="file" name="avatar" accept="image/*" />
<button type="submit">Upload</button>
</Form>import type { ApiRouteArgs } from "@pracht/core";
export async function POST({ request }: ApiRouteArgs) {
const form = await request.formData();
const file = form.get("avatar") as File;
if (!file || file.size === 0) {
return Response.json({ ok: false, error: "No file selected" }, { status: 400 });
}
const buffer = await file.arrayBuffer();
const url = await uploadToStorage(file.name, buffer);
return Response.json({ ok: true, url });
}Capability Form Feedback
For a capability form, group server validation issues with capabilityFormFeedback(). Failed enhanced submissions keep the current inputs, so visitors can correct them in place:
import { useState } from "preact/hooks";
import { Form } from "@pracht/core";
import { capabilityFormFeedback } from "@pracht/capabilities";
export function NoteForm() {
const [errors, setErrors] = useState<string[]>([]);
return (
<Form capability="notes.create" onCapabilityResult={(result) => {
setErrors(result.ok ? [] : capabilityFormFeedback(result.error).fieldErrors.title ?? []);
}}>
<label for="title">Title</label>
<input id="title" name="title" aria-invalid={errors.length > 0} aria-describedby="title-errors" />
<p id="title-errors" role="alert">{errors.join(" ")}</p>
<button type="submit">Create note</button>
</Form>
);
}For visitors without JavaScript, add form to the server-only capability. The renderer receives grouped fieldErrors, formErrors, and only the text fields you select in retain. Choose public text fields; leave passwords and tokens out.
form: {
retain: ["title"],
redirectTo: "/notes",
onInvalid: ({ request, feedback }) => renderNoteRetry(request, feedback),
},renderNoteRetry() returns your form as an HTML Response with status 400 or 422. Render feedback.values.title through Preact, associate feedback.fieldErrors.title with the input, and post back to new URL(request.url).pathname. Successful retries return to redirectTo, with your deploy base added automatically.
The basic example's retry renderer shows the complete response. With JavaScript, the original form shows errors in place; without it, the retry page preserves selected text and lets the visitor submit corrected input.
Search forms
A GET <Form> submits like a plain HTML form: the browser loads the action with the fields as its query. Add clientNavigation to go through the client router instead; the page updates without a document reload, and useNavigation() reports the pending load.
import { Form } from "@pracht/core";
<Form method="get" action="/search" clientNavigation>
<input name="q" type="search" />
<button type="submit">Search</button>
</Form>The browser builds the query, replacing any query on the action. A cross-origin action, or a target/formtarget other than _self, still submits natively.