dimah-formv0.6.1
React

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.

lib/form-client.ts
"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

components/questionnaire.tsx
"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

Next steps

On this page