Client session
Create a headless fill session with visibility, drafts, and submit.
@dimah-form/react is the headless fill session.
It tracks visible fields, local answers, autosave, and submit. It does not ship inputs.
"use client";
import { createFormClient } from "@dimah-form/react";
import type { Form } from "@/lib/form";
export const formClient = createFormClient<Form>({
basePath: "/api/form",
});
export const { useFormClient, useFormResponse } = formClient;Prefer the bound hook from your client. The unbound useFormResponse import needs formClient.Provider.
basePath must match the server. Cross-origin cookies and auth headers:
Security. Full option list: Configuration.
Fill session
"use client";
import { emptyToNull, fieldLabel } from "@dimah-form/react";
import type { FormSnapshot } from "@dimah-form/react";
import { useFormResponse } from "@/lib/form-client";
export function Questionnaire({ form }: { form: FormSnapshot }) {
const q = useFormResponse<"onboarding">({
snapshot: form,
autosave: { debounceMs: 1000 },
onSubmitted: (row) => {
console.log(row.id);
},
});
if (q.inactive) return <p>This form is inactive.</p>;
return (
<form
onSubmit={(event) => {
event.preventDefault();
void q.submit();
}}
>
{q.visibleFields.map((field) => {
const binding = q.field(field.id);
return (
<label key={field.id}>
{fieldLabel(field)}
<input
value={typeof binding.value === "string" ? binding.value : ""}
disabled={binding.disabled}
onChange={(event) =>
binding.onChange(emptyToNull(event.target.value))
}
/>
{binding.error ? <span>{binding.error}</span> : null}
</label>
);
})}
<button type="submit" disabled={q.pending !== undefined || q.locked}>
Submit
</button>
</form>
);
}Pass response when you already loaded a row. The hook does not fetch the snapshot — load it with form.api.getForm or getForm on the client.
Branch on field.type yourself, or render with FormView.
State
import type { FormResponseSessionState } from "@dimah-form/react";Prop
Type
Actions
useFormResponse returns these. dispose exists on createFormResponseSession only.
import type { FormResponseActions } from "@dimah-form/react";Prop
Type
field(id) returns a FormFieldBinding.
Options
import type { UseFormResponseOptions } from "@dimah-form/react";Prop
Type
"submit" checks on submit. After a failed submit, edits clear resolved issues.
"change" also checks on each answer change.
For a stepped custom UI, validate only the current field ids before advancing:
const canAdvance = await q.validate("submit", { fields: currentFieldIds });Protocol access
The bound useFormClient() returns the same typed protocol client outside the
fill-session workflow:
const client = useFormClient();
async function loadSubmitted() {
return client.listResponses({
formId: "onboarding",
status: "submitted",
});
}Prefer this bound hook. The package-level hook requires formClient.Provider
and loses the instance-specific inference unless you supply it explicitly.
Frequently asked questions
q.field(id) is untyped at the DOM boundary — narrow value yourself, or use
the helpers in Custom rendering. @dimah-form/ui already
maps built-in types.
Read binding.errorCode and binding.errorParams. English binding.error is the fallback. Codes: Errors.