Skip to Content

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 → AppShell from manh/shell (menu with roles, count; publicPaths for public pages) · for a different frame use ProLayout, never a hand-built Layout.Sider.
  • Page title, actions, tabs → PageContainer (title, subTitle, extra as an array of buttons, tabList + onTabChange, content for a summary line) · don’t use <h1> + <Space>.
  • Long form or detail page with a sticky save bar → FooterToolbar (extra for a total or status, children are the buttons).

Work queues

  • Records to process by status → ProTable with tabs in toolbar.menu (type: "tab") that show Badge counts, request + params={{ tab }}, an action column with valueType: "option", and rowSelection + tableAlertOptionRender for bulk approval · don’t use Table with your own fetch.
  • Items that move through stages (production, pipeline, tickets) → a kanban board: ProCard split="vertical" or Row/Col, one column per status holding a ProList or a stack of Cards. 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, subTitle as a Tag, actions, extra) with tabs in toolbar.menu · fits items with 1–3 actions each.
  • Today’s tasks for one role → a ProCard grid of small ProLists (“Deliver today”, “Arriving soon”) on one page.

Lists of records

  • Searchable list → ProTable (search={{ labelWidth: "auto" }} built from the columns, valueEnum for 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 → LightFilter in toolbar.filter · many filters → ProTable search, or QueryFilter on a page without a table.
  • Rules or priorities the user reorders → DragSortTable (dragSortKey, onDragSortEnd).
  • Product cards, galleries → ProList grid={{ gutter: 16, column: 3 }} or Card + Image · CheckCard.Group when the user picks one or more cards.
  • Tree data (categories, bill-of-materials levels, org chart) → Table / ProTable with children rows, or Tree / TreeSelect for picking.

Entering data

  • Create or edit a record from a list → DrawerForm (6 or more fields, or line items) / ModalForm (up to 5 fields), trigger as the opening button, onFinish returns true to close, initialValues when editing · don’t open a separate page.
  • Documents with line items (orders, purchase requests, invoices) → EditableProTable inside the form (recordCreatorProps, editable.type="multiple", read-only money columns), or ProFormList for 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 with ProFormSelect request + showSearch (debounceTime).
  • Money, quantities, percentages → ProFormMoney (locale="vi-VN"), ProFormDigit (min, fieldProps.precision), ProFormSlider or ProFormDigit + %.
  • Dates → ProFormDatePicker / ProFormDateRangePicker with transform to the API format · don’t set format alone (check warns code.proform-date-format-submit).
  • Multi-step setup → StepsForm (one StepsForm.StepForm per step, onFinish on the last).
  • The same fields in a table, a form, and a detail view → one columns array + BetaSchemaForm (layoutType="DrawerForm" | "ModalForm" | "Form").
  • Confirming a risky action → Popconfirm (one click) · with a reason → ModalForm with a required ProFormTextArea · an irreversible bulk action → Modal.confirm that states the count and the amount.
  • Files and photos → Upload (listType="picture-card" for photos, beforeUpload to check type and size, customRequest calling your API or a presignPut URL), shown with Image (preview).

Reading a record

  • Record header → PageContainer: title + a status Tag + extra holding 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 same valueTypes as the table, dataSource from the detail API).
  • Where the record is in its lifecycle → Steps (current from 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) → ProTable with search={false}, toolBarRender={false}, pagination={false}, and a summary row for totals.
  • Printable documents (delivery notes, invoices) → Descriptions + Table (bordered, size="small") and a Print button that calls window.print().

Numbers and dashboards

  • KPI row → StatRow from manh/shell (title, value, description comparing with the last period, a mini chart, onClick) · one number per tile, 4 tiles at most.
  • Charts (all from @ant-design/charts; set height, 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) → Pie with innerRadius;
    • target against actual → Progress / Gauge / Liquid;
    • two measures on two scales → DualAxes;
    • drop-off across stages → Funnel.
  • Ranked list (top customers, late orders) → a small ProList / Table with Progress or Statistic in each row.
  • Due dates or bookings → Calendar with cellRender (antd v6, not dateCellRender), or ProTable grouped by date.

Feedback and states

  • Loading → Skeleton or the table’s loading · empty → Empty with 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 color from one valueEnum map · 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 status is lowercase ("success"), while the status in a ProTable valueEnum is 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

Last updated