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.
// Create/edit form in a DrawerForm: ProFormMoney ($), field groups, tooltip, past dates blocked, return true to close.
import { useState } from "react";
import { DrawerForm, PageContainer, ProCard, ProFormDatePicker, ProFormGroup, ProFormMoney, ProFormSelect, ProFormText, ProFormTextArea } from "@ant-design/pro-components";
import { App, Button, Empty, Listy } from "antd";
import { PlusOutlined } from "@ant-design/icons";
import dayjs from "dayjs";
type Req = { title: string; amount: number; category: string; neededBy?: string };
export default function Page() {
const { message } = App.useApp();
const [items, setItems] = useState<Req[]>([]);
return (
<PageContainer title="My requests">
<ProCard
title="Submitted"
headerBordered
extra={
<DrawerForm<Record<string, unknown>>
title="New purchase request"
width={560}
trigger={<Button type="primary" icon={<PlusOutlined />}>New request</Button>}
drawerProps={{ destroyOnHidden: true }}
submitter={{ searchConfig: { submitText: "Submit request", resetText: "Cancel" } }}
initialValues={{ category: "office" }}
onFinish={async (v) => {
setItems((x) => [{ title: String(v.title), amount: Number(v.amount), category: String(v.category), neededBy: v.neededBy ? String(v.neededBy) : undefined }, ...x]);
message.success("Request submitted — waiting for manager approval");
return true; // close the drawer
}}
>
<ProFormText name="title" label="Title" placeholder="e.g. Renew Microsoft 365" tooltip="Make it clear enough that your manager doesn't need to open the details" rules={[{ required: true, min: 3, message: "At least 3 characters" }]} />
<ProFormGroup>
<ProFormMoney name="amount" label="Amount" width="sm" customSymbol="$" locale="en-US" min={1} fieldProps={{ precision: 2 }} rules={[{ required: true, message: "Enter an amount" }]} />
<ProFormSelect name="category" label="Category" width="sm" valueEnum={{ office: "Office supplies", equipment: "Equipment", software: "Software", service: "Services" }} rules={[{ required: true }]} />
</ProFormGroup>
<ProFormDatePicker name="neededBy" label="Needed by" width="sm" fieldProps={{ format: "MM/DD/YYYY", disabledDate: (d: dayjs.Dayjs) => d.isBefore(dayjs().startOf("day")) }}
// submitted in the DISPLAY format ("11/20/2026") — convert to ISO for the API
transform={(v: string | undefined) => ({ neededBy: v ? ((p: string[]) => `${p[2]}-${p[0]}-${p[1]}`)(v.split("/")) : undefined })} />
<ProFormTextArea name="description" label="Description" placeholder="Reason, vendor, link to the quote…" fieldProps={{ rows: 4, maxLength: 2000, showCount: true }} />
</DrawerForm>
}
>
{items.length ? (
(items?.length ? (
<Listy items={items} itemRender={(r) => <div className="flex items-start gap-4">
<div className="min-w-0 flex-1">{r.title}{r.neededBy ? ` · needed by ${r.neededBy}` : ""}</div>
<div className="shrink-0"><b>{r.amount.toLocaleString("en-US", { style: "currency", currency: "USD" })}</b></div>
</div>}
rowKey={(_, i) => i}
rowHoverable={false}
/>
) : (
<Empty image={Empty.PRESENTED_IMAGE_SIMPLE} />
))
) : (
<Empty image={Empty.PRESENTED_IMAGE_SIMPLE} description="No requests yet — click “New request”." />
)}
</ProCard>
</PageContainer>
);
}
Build the "Form in a Drawer" screen for my app following the Manh UI playbook (framework_docs("pro")): Create/edit form in a DrawerForm: ProFormMoney, field groups, tooltips, no past dates, return true to close. Data comes from the app's API through useApiClient(); labels and fields follow my spec.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 inFooterToolbar.
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.
<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:
<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:
gridon the form +colProps={{ xl: 12 }}on the field. - Don’t mix
widthwithfieldProps.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:
<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.
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:
<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.
<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 form: StepsForm (fill in → confirm → result). The last step hides the buttons and shows a Result.
import { useState } from "react";
import { PageContainer, ProCard, ProFormDigit, ProFormSelect, ProFormText, StepsForm } from "@ant-design/pro-components";
import { Alert, Button, Descriptions, Result } from "antd";
export default function Page() {
const [current, setCurrent] = useState(0);
const [data, setData] = useState<Record<string, unknown>>({});
return (
<PageContainer title="Stock transfer" subTitle="Move stock between warehouses in 3 steps">
<ProCard>
<StepsForm
current={current}
onCurrentChange={setCurrent}
submitter={{
render: (props, dom) => (props.step === 2 ? null : dom),
submitButtonProps: { style: { minWidth: 120 } },
}}
onFinish={async () => true}
>
<StepsForm.StepForm name="fill" title="Details" onFinish={async (v) => { setData(v); return true; }}>
<ProFormSelect name="from" label="From warehouse" width="md" rules={[{ required: true }]} valueEnum={{ hn: "Chicago warehouse", hcm: "Dallas warehouse" }} />
<ProFormSelect name="to" label="To warehouse" width="md" rules={[{ required: true }]} valueEnum={{ hn: "Chicago warehouse", hcm: "Dallas warehouse", dn: "Denver warehouse" }} />
<ProFormText name="sku" label="SKU" width="md" placeholder="SKU-0001" rules={[{ required: true }]} />
<ProFormDigit name="qty" label="Quantity" width="sm" min={1} fieldProps={{ precision: 0 }} rules={[{ required: true }]} />
</StepsForm.StepForm>
<StepsForm.StepForm name="confirm" title="Confirm">
<Alert type="info" showIcon title="Double-check before creating the transfer — it can't be edited afterwards." style={{ marginBottom: 24 }} />
<Descriptions column={1} bordered size="small" items={[{ label: "From warehouse", children: String(data.from ?? "") }, { label: "To warehouse", children: String(data.to ?? "") }, { label: "SKU", children: String(data.sku ?? "") }, { label: "Quantity", children: String(data.qty ?? "") }]} />
</StepsForm.StepForm>
<StepsForm.StepForm name="done" title="Done">
<Result status="success" title="Transfer created" subTitle="The receiving warehouse will see it under “Incoming”."
extra={[<Button key="again" type="primary" onClick={() => setCurrent(0)}>Create another</Button>, <Button key="view">View transfer</Button>]} />
</StepsForm.StepForm>
</StepsForm>
</ProCard>
</PageContainer>
);
}
Build the "Multi-step form" screen for my app following the Manh UI playbook (framework_docs("pro")): Multi-step form: StepsForm (fill in → confirm → result). The last step hides the buttons and shows a Result. Data comes from the app's API through useApiClient(); labels and fields follow my spec.<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/DrawerFormdoesn’t clear its fields if you set onlydestroyOnHidden. For a create form, addformRef.current?.resetFields()inonOpenChange(false), or usedrawerProps.destroyOnClose/modalProps.destroyOnCloseand 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
ModalFormto 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.