ProTable
pro-tableCombines business-table columns, querying, sorting, selection, pagination, and toolbar actions.
Usage
Hosted Mode
Pass request, that is, ProTable will manage page/sort/filters/loading/data by itself and request the server on demand.
Hosting mode (server request)
No data | ||||||
0 items
tsx
const request = async (p) => {
const rows = await fetchEmployees(p.filters, p.sort);
const start = (p.page - 1) * p.pageSize;
return { data: rows.slice(start, start + p.pageSize), total: rows.length };
};
<ProTable
title="Employee List"
columns={columns}
request={request}
defaultPageSize={8}
enableRowSelection
search={{ fields: searchFields }}
/>Default sorting + fixed query parameters
defaultSorting allows request to be sorted for the first time; params is the condition for nailing the page context, and the shallow comparison changes will return to page 1 for rechecking. request/params can all be inlined and no requests will be repeated.
Department (fixed query parameters)
Default is in descending order of monthly salary
No data | |||||
0 items
tsx
<ProTable
title="Default is in descending order of monthly salary"
columns={columns}
defaultSorting={[{ id: "salary", desc: true }]}
params={{ dept }}
request={async (p) => {
const { rows, total } = await api.list({
page: p.page,
pageSize: p.pageSize,
sort: p.sort,
...p.filters,
...p.params,
});
return { data: rows, total };
}}
/>cursor Paging
paginationMode="cursor", request returns { data, nextCursor, hasMore }, with the previous/next page at the bottom.
cursor Paging (Previous Page/Next Page · None total)
No data | |||||
tsx
<ProTable
title="Log"
columns={columns}
request={request}
paginationMode="cursor"
defaultPageSize={8}
pageSizeOptions={[8, 16, 32]}
/>Display mode (controlled paging)
When managing data/paging, just pass data + pagination + search callback.
Employee List
| Employees 01 | 1 | R&D Department | Working | 2024-01-15 | ¥8,000 | |
| Employees 02 | 2 | Marketing Department | Resignation | 2024-02-15 | ¥9,500 | |
| Employees 03 | 3 | Finance Department | To be hired | 2024-03-15 | ¥11,000 | |
| Employees 04 | 4 | Human Resources Department | Working | 2024-04-15 | ¥12,500 | |
| Employees 05 | 5 | R&D Department | Resignation | 2024-05-15 | ¥14,000 | |
| Employees 06 | 6 | Marketing Department | To be hired | 2024-06-15 | ¥15,500 | |
| Employees 07 | 7 | Finance Department | Working | 2024-07-15 | ¥17,000 | |
| Employees 08 | 8 | Human Resources Department | Resignation | 2024-08-15 | ¥18,500 |
47 items
tsx
<ProTable
title="Employee List"
columns={columns}
data={pageData}
enableRowSelection
onReload={reload}
toolbarActions={<Button size="sm">+ New employee</Button>}
search={{ fields: searchFields, onSearch, onReset }}
pagination={{ page, pageSize, total, onPageChange: setPage }}
/>Simplified table
Compact density + full screen button off + no query area.
Compact table (no query area)
| Employees 01 | 1 | R&D Department | Working |
| Employees 02 | 2 | Marketing Department | Resignation |
| Employees 03 | 3 | Finance Department | To be hired |
| Employees 04 | 4 | Human Resources Department | Working |
| Employees 05 | 5 | R&D Department | Resignation |
tsx
<ProTable
title="Compact Table"
columns={columns.slice(0, 4)}
data={rows}
density="compact"
toolbar={{ fullscreen: false }}
/>When to use
Use ProTable for a complete enterprise list page: search form, toolbar, table, and pagination in one component. Prefer it for server pagination, sorting, and filtering. Table is the lower-level table skin; ProTable's managed mode also owns the request lifecycle.
Import
ts
import { ProTable } from "@hulianui/ui"Props
Inherits Omit<TableProps<TData>, "data">, including columns, sorting, selection, density, row identity, and row classes, and adds:
Enablevirtualfor large result sets. It is inherited from Table even though it is not repeated in the table below: ``tsx <ProTable columns={columns} request={fetchRows} virtual={{ enabled: true, height: 480 }} />`See [Tablevirtual](/en/components/table) for parameters and constraints. It requires@tanstack/react-virtual` and is not recommended with trees, expanded detail panels, or row drag-and-drop.
| Name | Type | Default | Description |
|---|---|---|---|
| data | TData[] | — | Required in display mode; ignored when request enables managed mode. |
| request | (params: ProTableRequestParams) => Promise<ProTableRequestResult<TData>> | — | Enables managed data, paging, sorting, filters, loading, and selection. Held in a ref, so function identity is not a request dependency. |
| params | Record<string, unknown> | — | Fixed managed-mode parameters. Shallow changes reset to page one and re-request; values remain separate from filters. |
| paginationMode | "page" | "cursor" | "page" | Page mode returns {data,total}; cursor mode receives a cursor and returns {data,nextCursor,hasMore}. |
| defaultPageSize | number | 10 | Initial managed page size. |
| defaultSorting | SortingState | [] | Initial managed sorting, read only on first mount and sent with the first request. |
| pageSizeOptions | number[] | — | Renders a page-size selector when supplied. |
| pagination | ProTablePagination | — | Display-mode footer pagination: {page,pageSize,total,onPageChange,showFirstLast?,onPageSizeChange?}. |
| search | Omit<SearchFormProps,"onSearch"> & { onSearch? } | — | Integrated SearchForm; onSearch is optional in managed mode. |
| toolbar | boolean | ProTableToolbarFeatures | true | True enables all tools, false hides the toolbar, or configure reload, density, column settings, and fullscreen individually. |
| loading | boolean | — | Display-mode loading state, including the rotating refresh icon. |
| actionRef | Ref<ProTableActions> | — | Exposes reload() and clearSelection(). |
| rootClassName | string | — | Outer container class, distinct from the Table className. |
Events
Inherited Table events include sorting, selection, expansion, and column-filter changes. ProTable adds:
| Event | Type | Description |
|---|---|---|
| onReload | () => void | Called from the toolbar reload control. |
| onRequestError | (error: unknown) => void | Managed request failure handler; defaults to console.error, resets loading, and preserves previous data. |
Slots
| Slot | Type | Description |
|---|---|---|
| title | ReactNode | Card title on the left side of the toolbar. |
| toolbarActions | ReactNode | Custom actions before the built-in toolbar controls. |
| batchActions | (ctx: ProTableBatchCtx) => ReactNode | Renders batch operations when selection is enabled and rows are selected. |
Usage notes
- In managed mode,
data,pagination, andloadingare ignored. Cursor mode has no total or random page jump; changing filters, sorting, or page size resets to page one. - Supply
getRowIdin managed mode so selection remains stable across pages.batchActionsalso requires enabled selection and at least one selected row. - Request rejection falls back to
console.error; useonRequestErrorfor a production toast or report. requestis held in a ref. Inline functions do not loop, but replacing only the function does not reload; changeparamsor callactionRef.reload().defaultSortingis an uncontrolled initial value. Later changes do not overwrite user sorting; remount with a key or use controlledsorting.paramsis compared only one level deep. Flat inline objects are safe; keep nested values referentially stable or flatten them.paramsstays separate fromfilters, so fixed constraints cannot be reset or overwritten by the search form. Merge them explicitly insiderequest.- Any
paramscontent change resets page mode to page one and cursor mode to the start.
Related
Table · Book3D · PricingTable · JsonViewer · EditableTable · List