Skip to Content

Forms

Forms that create and edit records: choose between DrawerForm, ModalForm, StepsForm, and an on-page ProForm, format money and dates, add line items, and show server errors.

pro-components forms handle the submit button, the submitting state, closing when done and required fields. You declare the fields, call the API in onFinish and return true to close. For example, a purchase request form with amount, category and needed-by date.

Form in a DrawerCreate/edit form in a DrawerForm: ProFormMoney, field groups, tooltips, no past dates, return true to close.
example.manh.run · sample dataOpen in editor ↗
The example runs when you scroll to it

Choose a form type

  • DrawerForm — create or edit a record from a list, with 6 or more fields or with line items.
  • ModalForm — up to 4–5 fields, or a decision with a note (approve, reject).
  • StepsForm — a long flow split into steps: fill in → confirm → result.
  • On-page ProForm — long forms such as settings, profiles, or multi-part documents; the submit button sits in FooterToolbar.

Don’t open a separate page to create one record from a list.

A create and edit form in a drawer

Use one component for both Create request on the list and Edit on the detail page; when initial is set, the form edits.

app/requests/request-form.tsx
<DrawerForm title={title} trigger={trigger} width={560} drawerProps={{ destroyOnHidden: true }} submitter={{ searchConfig: { submitText: initial ? "Save changes" : "Submit request", resetText: "Cancel" } }} initialValues={initial ?? { category: "office" }} onFinish={async (v) => { await onSubmit(v); return true; }} // true = close the drawer > <ProFormText name="title" label="Title" tooltip="Enough for a manager to understand without opening it" rules={[{ required: true, min: 3, max: 200, message: "3–200 characters" }]} /> <ProFormGroup> <ProFormMoney name="amount" label="Amount" width="sm" customSymbol="₫" locale="vi-VN" min={1} fieldProps={{ precision: 0 }} rules={[{ required: true, message: "Enter an amount above 0" }]} /> <ProFormSelect name="category" label="Category" width="sm" valueEnum={CATEGORY_ENUM} rules={[{ required: true }]} /> </ProFormGroup> <ProFormTextArea name="description" label="Description" fieldProps={{ rows: 5, maxLength: 2000, showCount: true }} /> </DrawerForm>

On the list, call actionRef.current?.reload() after a successful submit so the table reloads.

Show DD/MM/YYYY, send YYYY-MM-DD

A date field with fieldProps.format submits the exact string it displays (“20/11/2026”), and the API rejects it. Convert the value on the field with transform:

app/requests/request-form.tsx
<ProFormDatePicker name="neededBy" label="Needed by" width="sm" fieldProps={{ format: "DD/MM/YYYY", disabledDate: (d) => d.isBefore(dayjs().startOf("day")) }} transform={(v) => ({ neededBy: v ? v.split("/").reverse().join("-") : undefined })} />

Or drop format so the form submits YYYY-MM-DD.

Field widths and groups

  • width="xs" | "sm" | "md" | "lg" | "xl" (104 / 216 / 328 / 440 / 552 px) keeps an even rhythm.
  • For columns that adapt to the screen: grid on the form + colProps={{ xl: 12 }} on the field.
  • Don’t mix width with fieldProps.style.width.
  • Several short fields on one row: wrap them in ProFormGroup.

Fields that depend on other fields

Show a field based on another field’s value with ProFormDependency:

app/orders/order-form.tsx
<ProFormRadio.Group name="delivery" label="Delivery" options={[ { label: "Ship to address", value: "ship" }, { label: "Pick up in store", value: "pickup" }, ]} /> <ProFormDependency name={["delivery"]}> {({ delivery }) => delivery === "ship" ? <ProFormText name="address" label="Shipping address" rules={[{ required: true }]} /> : <ProFormSelect name="storeId" label="Store" request={loadStores} showSearch />} </ProFormDependency>

Line items in a form

Give EditableProTable a name and it becomes a field: onFinish receives values.lines. Remove the temporary key before you send; the server computes prices and totals.

app/orders/order-form.tsx
const [keys, setKeys] = useState<React.Key[]>([]); <EditableProTable<Line> name="lines" rowKey="key" columns={lineColumns} // money columns are read-only recordCreatorProps={{ position: "bottom", record: () => ({ key: Date.now() }), creatorButtonText: "Add line" }} editable={{ type: "multiple", editableKeys: keys, onChange: setKeys }} /> // onFinish: lines.map(({ key, ...l }) => l)

For rows with 1–2 fields, ProFormList is shorter.

Long forms on a page

Put settings or multi-part documents on a page, split into one ProCard per section, with the submit button stuck to the bottom:

app/settings/page.tsx
<ProForm layout="vertical" onFinish={save} submitter={{ render: (_, dom) => <FooterToolbar>{dom}</FooterToolbar> }}> <ProCard title="Company" headerBordered>{/* … */}</ProCard> <ProCard title="Invoices" headerBordered>{/* … */}</ProCard> </ProForm>

Show server errors

The API returns 4xx errors with a { error, message, code } body. Wrap onFinish in submit from app/hooks: it calls the API, shows the success message, reloads the table and returns true to close the form. On an error, field errors from the server appear under their fields, anything else shows the server’s message, and the form stays open.

app/requests/request-form.tsx
<DrawerForm form={form} title="New request" onFinish={submit((v) => api.requests.create(v), { done: "Request sent", reload: tableRef, form })}> {/* … */} </DrawerForm>

To show the error text somewhere else, use errorText(e) from manh/shell.

Step forms

StepsForm splits a long flow into steps; each StepsForm.StepForm validates its own fields before the next step. The last step is a Result, so hide the buttons there.

Multi-step formMulti-step form: StepsForm (fill in → confirm → result). The last step hides the buttons and shows a Result.
example.manh.run · sample dataOpen in editor ↗
The example runs when you scroll to it
app/onboarding/page.tsx
<StepsForm onFinish={async (v) => { await api.shops.create(v); return true; }} submitter={{ render: (p, dom) => (p.step === 2 ? null : dom) }}> <StepsForm.StepForm name="info" title="Details">{/* … */}</StepsForm.StepForm> <StepsForm.StepForm name="confirm" title="Confirm">{/* Descriptions + Alert */}</StepsForm.StepForm> <StepsForm.StepForm name="done" title="Done"><Result status="success" title="Shop created" /></StepsForm.StepForm> </StepsForm>

Good to know

  • Reopening a ModalForm / DrawerForm doesn’t clear its fields if you set only destroyOnHidden. For a create form, add formRef.current?.resetFields() in onOpenChange(false), or use drawerProps.destroyOnClose / modalProps.destroyOnClose and accept the development warning.
  • Never render a raw error object: an object as a React child crashes the page.
  • Money: ProFormMoney (customSymbol="₫", locale="vi-VN", precision: 0); numbers: ProFormDigit; date ranges: ProFormDateRangePicker.
  • Write button labels in the user’s language with submitter.searchConfig.

Next steps

  • Detail pages — a ModalForm to approve or reject with a note.
  • List pages — where the New request button opens a Drawer.
  • API handlers — validate submitted data with Zod on the server.
Last updated