Pick a component by job
A lookup for choosing components: what the user does on the screen, which antd, pro-components, charts, or antd X component to use, which props to set, and which mistake to avoid.
Choose by the job the user does, not by the shape of the data. Each line has three parts: component · props that make it right · the mistake to avoid.
Pages and navigation
- App shell, menu per role →
AppShellfrommanh/shell(menuwithroles,count;publicPathsfor public pages) · for a different frame useProLayout, never a hand-builtLayout.Sider. - Page title, actions, tabs →
PageContainer(title,subTitle,extraas an array of buttons,tabList+onTabChange,contentfor a summary line) · don’t use<h1>+<Space>. - Long form or detail page with a sticky save bar →
FooterToolbar(extrafor a total or status, children are the buttons).
Work queues
- Records to process by status →
ProTablewith tabs intoolbar.menu(type: "tab") that show Badge counts,request+params={{ tab }}, an action column withvalueType: "option", androwSelection+tableAlertOptionRenderfor bulk approval · don’t useTablewith your own fetch. - Items that move through stages (production, pipeline, tickets) → a kanban board:
ProCard split="vertical"orRow/Col, one column per status holding aProListor a stack ofCards. Drag between columns with@dnd-kit, only to the allowed next stage, and add a “Move to next step” button for touch and keyboard users · don’t use a table when the user thinks in columns. - My inbox or approvals →
ProList(metas:title,description,subTitleas a Tag,actions,extra) with tabs intoolbar.menu· fits items with 1–3 actions each. - Today’s tasks for one role → a
ProCardgrid of smallProLists (“Deliver today”, “Arriving soon”) on one page.
Lists of records
- Searchable list →
ProTable(search={{ labelWidth: "auto" }}built from the columns,valueEnumfor status and select fields,valueType: "money" | "percent" | "dateTime" | "dateRange",hideInSearch/hideInTable,fieldProps),pagination.showTotal,options={{ density: true, setting: false }}· the server returns{ data, total }. - A few compact filters →
LightFilterintoolbar.filter· many filters →ProTablesearch, orQueryFilteron a page without a table. - Rules or priorities the user reorders →
DragSortTable(dragSortKey,onDragSortEnd). - Product cards, galleries →
ProList grid={{ gutter: 16, column: 3 }}orCard+Image·CheckCard.Groupwhen the user picks one or more cards. - Tree data (categories, bill-of-materials levels, org chart) →
Table/ProTablewithchildrenrows, orTree/TreeSelectfor picking.
Entering data
- Create or edit a record from a list →
DrawerForm(6 or more fields, or line items) /ModalForm(up to 5 fields),triggeras the opening button,onFinishreturnstrueto close,initialValueswhen editing · don’t open a separate page. - Documents with line items (orders, purchase requests, invoices) →
EditableProTableinside the form (recordCreatorProps,editable.type="multiple", read-only money columns), orProFormListfor short repeated groups. After saving, show the total the server computed · never let the client send prices or totals. - A field that depends on another (customer → address, product → unit price) →
ProFormDependency/Form.useWatch; load options from the API withProFormSelect request+showSearch(debounceTime). - Money, quantities, percentages →
ProFormMoney(locale="vi-VN"),ProFormDigit(min,fieldProps.precision),ProFormSliderorProFormDigit+%. - Dates →
ProFormDatePicker/ProFormDateRangePickerwithtransformto the API format · don’t setformatalone (checkwarnscode.proform-date-format-submit). - Multi-step setup →
StepsForm(oneStepsForm.StepFormper step,onFinishon the last). - The same fields in a table, a form, and a detail view → one
columnsarray +BetaSchemaForm(layoutType="DrawerForm" | "ModalForm" | "Form"). - Confirming a risky action →
Popconfirm(one click) · with a reason →ModalFormwith a requiredProFormTextArea· an irreversible bulk action →Modal.confirmthat states the count and the amount. - Files and photos →
Upload(listType="picture-card"for photos,beforeUploadto check type and size,customRequestcalling your API or apresignPutURL), shown withImage(preview).
Reading a record
- Record header →
PageContainer:title+ a statusTag+extraholding the actions this role can take in this status. Hide (don’t disable) actions this role can never take. - Fields →
ProDescriptions(column={{ xs: 1, md: 2, xl: 3 }}, the samevalueTypes as the table,dataSourcefrom the detail API). - Where the record is in its lifecycle →
Steps(currentfrom the status,status="error"when cancelled or rejected) · status buttons →FlowActions· history →ActivityLog(who · what · when, newest first). - Related lists (line items, payments, stock movements) →
ProTablewithsearch={false},toolBarRender={false},pagination={false}, and asummaryrow for totals. - Printable documents (delivery notes, invoices) →
Descriptions+Table(bordered,size="small") and a Print button that callswindow.print().
Numbers and dashboards
- KPI row →
StatRowfrommanh/shell(title,value,descriptioncomparing with the last period, a minichart,onClick) · one number per tile, 4 tiles at most. - Charts (all from
@ant-design/charts; setheight,autoFit, and an axis label formatter for money):- trend over time →
Line/Area; - compare categories →
Column/Bar; - share of a whole (6 parts at most) →
PiewithinnerRadius; - target against actual →
Progress/Gauge/Liquid; - two measures on two scales →
DualAxes; - drop-off across stages →
Funnel.
- trend over time →
- Ranked list (top customers, late orders) → a small
ProList/TablewithProgressorStatisticin each row. - Due dates or bookings →
CalendarwithcellRender(antd v6, notdateCellRender), orProTablegrouped by date.
Feedback and states
- Loading →
Skeletonor the table’sloading· empty →Emptywith one sentence and a next-step button · error, no permission, done →Result(status="403" | "404" | "success" | "warning"). - Short feedback after an action →
App.useApp().message· long-running or cross-page work →notification· show server 4xx text as is. - Status everywhere →
Badge status/Tag colorfrom onevalueEnummap · overdue or short stock →Typography.Text type="danger". - First-run guidance →
Tour· a watermark on printed or exported pages →Watermark.
AI features
Add them only when the product needs them. Use @ant-design/x: chat = Bubble.List + Sender, suggestions = Prompts, conversation list = Conversations. On the server, call manh/openai.
Good to know
- antd
Badge statusis lowercase ("success"), while thestatusin a ProTablevalueEnumis capitalized ("Success"). If you share one map between them, convert between the two, or the colored dots silently disappear. - Kanban drag and drop is only the interface: the API must still refuse a skipped stage.
Next steps
- App shell and page header — build
AppShellandPageContainerbefore any other screen. - List pages — a complete
ProTablewith a runnable example. - Diagrams, kanban, AI chat — when tables and forms are not enough.
Last updated