dimah-formv0.6.1

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.json

Render the session

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

Next

On this page