UI
Render an existing fill session with optional shadcn components.
@dimah-form/ui renders a FormResponseApi from your existing
useFormResponse call. It never creates or forks a fill session, so you can
start with headless controls and add this package only when it fits your UI.
npm i @dimah-form/ui @dimah-form/react@import "@dimah-form/ui/styles.css";The package expects the standard shadcn runtime peers. If your package manager
does not install peers automatically, add @base-ui/react,
@fuma-translate/react, class-variance-authority, cn, and lucide-react.
Or copy the source with the shadcn registry:
pnpm dlx shadcn@latest add https://form.dimah.dev/r/form.jsonRender the session
"use client";
import type { FormSnapshot } from "@dimah-form/react";
import { FormUiProvider, FormView } from "@dimah-form/ui";
import { useFormResponse } from "@/lib/form-client";
export function Questionnaire({ snapshot }: { snapshot: FormSnapshot }) {
const form = useFormResponse({ snapshot });
return (
<FormUiProvider>
<FormView form={form} />
</FormUiProvider>
);
}import type { FormUiProviderProps, FormViewProps } from "@dimah-form/ui";FormUiProvider
Prop
Type
FormView
Prop
Type
The built-in widgets cover text, email, date, number, boolean,
select, and multiSelect. file has no upload widget. Register custom
widgets by the same type string used by defineFieldType, or choose a
registered widget with field.meta.widget.
Built-in presentation variants are radio for select, switch for
boolean, and chips for multiSelect. They are widget modes, not registry
keys.
layout="auto" becomes a wizard when fields use meta.step; it renders review
mode for locked responses. Force fill, steps, or review with layout or
form.meta.layout.
Customize safely
Slots—such as header, progress, errorSummary, and actions—accept
false, a node, or a wrapper function. render replaces the layout; keep
FormRoot inside it so submit and Enter behavior remain intact.
<FormUiProvider
components={{ RequiredMark, FieldFrame: MyFieldFrame }}
formatIssue={(binding) =>
binding.errorCode === "TOO_SMALL" ? "Pick a higher score" : undefined
}
>
<FormView form={form} />
</FormUiProvider>import type { FormUiComponents } from "@dimah-form/ui";Prop
Type
Use FormFieldFrame inside a custom widget so the consuming application's
FieldFrame component and accessibility chrome still apply.
Compose from primitives
Use FormView for the standard layout. When the application needs full
control, compose the same session without creating another hook:
import {
FormActions,
FormFields,
FormHeader,
FormRoot,
FormScope,
} from "@dimah-form/ui";
<FormUiProvider>
<FormScope form={form}>
<FormRoot>
<FormHeader />
<FormFields />
<FormActions />
</FormRoot>
</FormScope>
</FormUiProvider>;Keep FormRoot in custom compositions so submit, Enter handling, invalid-field
focus, and step navigation remain connected to the session.
Localize UI and request errors
English source strings are the fallback. Pass a partial translation map for
UI copy, formatIssue for field codes, and formatSessionError for request
errors.
import type { Translations } from "@dimah-form/ui";
const fa = {
"Submit(form action)": "ارسال",
} satisfies Partial<Translations>;
<FormUiProvider
translations={fa}
formatSessionError={(session) =>
session.errorCode === "UNAUTHORIZED" ? "Please sign in" : undefined
}
>
<FormView form={form} />
</FormUiProvider>;Type UI metadata
import { defineForm } from "@dimah-form/server";
import type { FormDefinitionUi } from "@dimah-form/ui/types";
export const onboarding = defineForm({
meta: { layout: "steps", steps: { "1": "About you", "2": "Work" } },
fields: [{ id: "name", type: "text", meta: { placeholder: "Ada", step: 1 } }],
} satisfies FormDefinitionUi);import type { FieldUiMeta, FormUiMeta } from "@dimah-form/ui";FieldUiMeta
Prop
Type
FormUiMeta
Prop
Type
Extra metadata is allowed. Add a metaSchema to dimahForm() when
database-authored forms need server-side validation of that metadata.