# Table
- Page: https://jiguang132.com/resources/arco-design/docs/table
- Resource: Arco Design (https://jiguang132.com/resources/arco-design.md)
- All guides: https://jiguang132.com/resources/arco-design/docs.md
Used for data collection, display, analysis, and processing.
## Install
```bash
npm install @arco-design/web-react@2.66.18
```
Import `@arco-design/web-react/dist/css/arco.css` at the entry and set the locale with `ConfigProvider`. React 19 projects must also import `@arco-design/web-react/es/_util/react-19-adapter` first, or imperative APIs such as Message and Modal cannot render.
## Examples
- **Basic**: The simplest usage.
- **Selection**: Table enable selection, you can set `rowSelection.type` to use checkbox and radio.
- **Expandable row**: When the content is too long, you can set the expanded row by `expandedRowRender`. If the return value is `null`, the expand button will not be rendered.
- **Expand props**: The icon, width, title, expandable etc. of the expanded column can be customized through `expandProps`. **Tip:** whether to expandable or not is determined by the return value of `expandedRowRender`. If too many `expandedRowRender` calculations block page render, it is recommended to use `expandProps.rowExpandable`.
- **Nested Table**: Examples of nested tables, click the expand button to display the sub tables in the expanded area.
- **Tree Data**: There is a `children` field in `data`, or set as a custom field by `childrenColumnName` to display tree data.
- **Attributes**: You can easily open or close the properties of the table.
- **Sort and filter**: Configure the `sorter` of `Column` to sort the table. Configure the `filters` of `Column` to filter the table. `sorter` is a sorting function. You can also specify `sorter` to `true`, so that you can customize the sorting through the `onChange` event of `Table`. `filters` is an array containing the information to be filtered, which needs to be used with `onFilter`. You can also use the `onChange` event of the `Table` for custom filtering or server-side filtering. **Default sort and filter**: You can specify the default sort and filter by specifying `defaultFilters` and `defaultSortOrder`.
- **Custom filter dropdown**: Custom filter dropdown.
- **Multiple sorter**: `column.sorter` supports passing in an object that has a `multiple` property that can be used to sort multiple columns. `multiple` is of type `number`. The larger the number, the higher the sorting priority. ** Note: ** Multiple column sorting with `sortOrder` when used, in order to maintain state consistency, all specified `sorter` columns need to specify `sortOrder` (can be undefined), while needing to pay attention to the mutual exclusion relationship between columns.
- **Custom pagination**: Custom pagination, by setting `total`, `pageSize`, and `onChange` to dynamically update table data. When the pagination setting `simple` is `true`, the simple pagination style will be applied. For the specific settings of `pagination`, please refer to the [pagination component](/react/components/Pagination) document. Through `renderPagination`, you can customize the pagination render.
- **Custom cell content**: The content of the cell can be customized through the `render` field in `columns`.
- **Fixed columns**: Specify `fixed: "left"` or `fixed: "right"` in `column` to fix the column to the left or right. To set the column of `fixed`, you also need to set `width`. **Note:** To be used with `scroll={{ x: number }}`, there needs to be a column in `columns` that does not set the width and is adaptive, otherwise there will be style problems.
- **Customize style**: There are many ways to customize the row and column styles. `rowClassName` can customize the style of each row, and `Column.className` can customize the style of columns. In addition, there are `headerCellStyle` and `bodyCellStyle` to customize the styles of the columns of the table header and table body.
- **Group columns**: `children` can be nested in `columns` for group columns.
- **Cell merge**: Used for cell merging, the header can only be column merged.
- **Editable cell**: Editable cell.
- **Custom operation column**: You can customize the operation column through `components`, including adding new columns, adjusting the order of columns, etc.
- **Big Data**: Built-in virtual scrolling logic, set `virtualized=true` to enable. **Note:** After enabling virtual scrolling, do not set the width for each column. Make sure that one column is adaptive, otherwise there may be misalignment between the header and the body.
- **No Data Element**: When the table has no data, a centered prompt message will be displayed by default. You can customize the display content when there is no data by using the `noDataElement` property.
- **Summary**: The usage of summary.
Examples come from the official Arco Design repository (MIT) at the commit published as npm 2.66.18. Some use online images or upload endpoints; network requests are disabled in previews.
## API
### Table
|Property|Description|Type|DefaultValue|Version|
|---|---|---|---|---|
|borderCell|Whether to display the table cell border, equivalent to `border={{ cell: true }}`|boolean |`-`|-|
|defaultExpandAllRows|Expand all expandable rows by default|boolean |`-`|-|
|hover|Whether to enable the hover style|boolean |`true`|-|
|showHeader|Whether to show the header|boolean |`true`|-|
|stripe|Whether to show stripe style|boolean |`-`|-|
|tableLayoutFixed|The table's `table-layout` property is set to `fixed`. After set to `fixed`, the width of the table will not be stretched by the content beyond 100%.|boolean |`-`|-|
|virtualized|The table enables virtual scrolling for processing big data scenarios.(Note: Virtual scrolling will automatically turn off support for tree data)|boolean |`-`|-|
|indentSize|The pixel offset to the left of each level of the tree data|number |`15`|-|
|childrenColumnName|The field name of the tree data in `data`, default is `children`|string |`children`|-|
|onChange|Callback when pagination, sorting, and filtering changes|(pagination: [PaginationProps](pagination#pagination),sorter: [SorterInfo](#sorterinfo) \| [SorterInfo](#sorterinfo)[],filters: Partial<Record<keyof T, string[]>>,extra: { currentData: T[]; currentAllData: T[]; action: 'paginate' \| 'sort' \| 'filter' }) => void |`-`|extra in `2.19.0`, currentAllData in 2.53.0|
|pagePosition|Set the position of the pagination, there are six positions `bottom right` `bottom left` `top right` `top left` `top center` `bottom center`|'br' \| 'bl' \| 'tr' \| 'tl' \| 'topCenter' \| 'bottomCenter' |`br`|-|
|size|The table size is divided into four sizes, `default` `medium` `small` `mini`|'default' \| 'middle' \| 'small' \| 'mini' |`-`|-|
|noDataElement|Element to be displayed when there is no data|string \| ReactNode |``|-|
|placeholder|When the cell content is empty, a placeholder is displayed, and the priority is lower than `column.placeholder`.|ReactNode |`-`|2.23.0|
|border|Configure border|\| boolean\| { wrapper?: boolean; headerCell?: boolean; bodyCell?: boolean; cell?: boolean } |`true`|-|
|className|Additional css class|string \| string[] |`-`|-|
|columns|An array of column objects|[ColumnProps](table#column)<T>[] |`-`|-|
|components|Override native table tag|[ComponentsProps](#componentsprops) |`-`|-|
|data|Data record array to be displayed|T[] |`-`|-|
|defaultExpandedRowKeys|To set default expanded rows|(string \| number)[] |`-`|-|
|expandedRowKeys|To set expanded rows.|(string \| number)[] |`-`|-|
|expandProps|Customize the icon, width, and title of the expandable column, see [this example](/react/components/table#custom expand parameters) for usage|[ExpandProps](table#expandprops)<T> |`-`|-|
|loading|Whether the table is in loading|boolean \| [SpinProps](spin#spin) |`-`|-|
|onHeaderRow|Set the event callback of the header row|(columns: [ColumnProps](table#column)<T>[], index: number) => [RowCallbackProps](#rowcallbackprops) |`-`|-|
|pagination|Pagination settings, refer to [Pagination components](/react/components/pagination), set `false` to hide pagination|[PaginationProps](pagination#pagination) \| boolean |`-`|-|
|rowSelection|Set whether the table row is selectable, select event, etc. [Configuration item](#rowselection)|[RowSelectionProps](table#rowselection)<T> |`-`|-|
|scroll|Set the scroll of x-axis or y-axis. Setting `x` to `true` will add `table-layout: fixed` to the table and `overflow: auto` to the parent element.If `y` is set to `true`, the header and body will be separated and placed in two tables|{ x?: number \| string \| boolean; y?: number \| string \| boolean } |`-`|-|
|showSorterTooltip|Whether the header shows the tooltip for the next sorting. The object can be set,and all the parameters of the `Tooltip` component can be passed.|boolean \| [TooltipProps](tooltip#tooltip) |`true`|2.19.0|
|style|Additional style|CSSProperties |`-`|-|
|virtualListProps|Used to configure `VirtualList`.|[AvailableVirtualListProps](#availablevirtuallistprops) |`-`|2.46.0|
|expandedRowRender|Click to expand additional rows, rendering functions. When the return value is `null`, the expand button will not be rendered|(record: T, index: number) => ReactNode |`-`|-|
|footer|The footer of the table|(currentPageDate) => ReactNode |`-`|-|
|onExpand|Callback when click to expand|(record: T, expanded: boolean) => void |`-`|-|
|onExpandedRowsChange|Callback when expanded button is clicked, the parameter is an array of expanded rows|(expandedRows: (string \| number)[]) => void |`-`|-|
|onRow|Set the event callback of the table row|(record: T, index: number) => [RowCallbackProps](#rowcallbackprops) |`-`|-|
|renderPagination|Customized pagination render|(paginationNode?: ReactNode) => ReactNode |`-`|2.11.0|
|rowClassName|ClassName of table row|(record: T, index: number) => string |`-`|-|
|rowKey|Table row key|React.Key \| ((record: T) => React.Key) |`key`|-|
|summary|Table Summary|(currentData?: T[]) => ReactNode |`-`|2.17.0|
### RowSelection
The detailed parameters of `rowSelection`.
|Property|Description|Type|DefaultValue|Version|
|---|---|---|---|---|
|checkAll|Whether to show check all button|boolean |`-`|-|
|checkCrossPage|Whether the checkboxes in multi-select mode cross pages, only works in uncontrolled mode, but also works in controlled mode with preserveSelectedRowKeys: true.|boolean |`-`|-|
|checkStrictly|When set to `false`, parent-child selections are automatically associated.|boolean |`true`|2.33.0|
|fixed|Whether to fix column to the left|boolean |`-`|-|
|preserveSelectedRowKeys|The `key` is still retained in `selectedRowKeys` when the data item is deleted|boolean |`-`|2.19.0|
|columnWidth|The width of the selection column|number |`-`|-|
|type|Multi-select or single-select|'checkbox' \| 'radio' |`-`|-|
|columnTitle|Customize the title of the selection column|string \| ReactNode |`-`|-|
|selectedRowKeys|Table selected row, (controlled mode, need to be used with `onChange`)|(string \| number)[] |`-`|-|
|checkboxProps|Configure the selection checkbox|(record: T) => { [key: string]: any } |`-`|-|
|onChange|Callback when the checkbox/radio changes|(selectedRowKeys: (string \| number)[], selectedRows: T[]) => void |`-`|-|
|onSelect|Callback for user manual selection/deselection|(selected: boolean, record: T, selectedRows: T[]) => void |`-`|2.22.0|
|onSelectAll|Callback when the user to manually select/deselect all rows|(selected: boolean, selectedRows) => void |`-`|2.6.0|
|renderCell|Customize checkbox, the usage is same as `column.render`.|(originNode, checked: boolean, record: T) => ReactNode |`-`|2.19.0|
### ExpandProps
The detailed parameters of `expandProps`.
|Property|Description|Type|DefaultValue|Version|
|---|---|---|---|---|
|expandRowByClick|Clicking on the row to expand|boolean |`-`|2.19.0|
|strictTreeData|For tree data, only when `children` is an array and the length is greater than 1, the expand icon will be displayed.|boolean |`true`|2.27.0|
|width|The width of expand icon column|number |`-`|-|
|columnTitle|The table header title of expand icon column|ReactNode |`-`|-|
|icon|Customize the icon of the expand button|(props: { expanded: boolean; record: Record<string, any> }) => ReactNode |`-`|-|
|rowExpandable|Whether to allow row expansion. If this parameter is not specified,it will be determined by whether expandedRowRender has a return value. When performance problems occur, rowExpandable is recommended.|(record: T) => boolean |`-`|2.16.0|
### Column
The column describes the data object and is an item in `columns`.
|Property|Description|Type|DefaultValue|Version|
|---|---|---|---|---|
|ellipsis|If the cell content exceeds the length, whether it is automatically omitted and displays `...`.After setting this property, the `table-layout` of the table will automatically become `fixed`.|boolean |`-`|-|
|filterMultiple|Is it possible to filter multiple items|boolean |`true`|-|
|dataIndex|The `key` corresponding to the column data in the data item is used to display the value.It supports the nested writing of `a[0].bc[1]`, see [lodash.get](https:// www.npmjs.com/package/lodash.get).|string |`-`|-|
|align|Set the alignment of the column|'left' \| 'center' \| 'right' |`left`|-|
|defaultSortOrder|To set default sort order|'ascend' \| 'descend' |`-`|-|
|fixed|Fixed header and column to the left or right|'left' \| 'right' |`-`|-|
|sortDirections|Supported sorting methods.|Array<'ascend' \| 'descend'> |`['ascend','descend']`|-|
|sortOrder|To set sort order, which can control the sorting of columns, can be set to `ascend` `descend`|'ascend' \| 'descend' |`-`|-|
|filterIcon|Custom filter icon.|ReactNode |`-`|-|
|placeholder|When the cell content is empty, a placeholder is displayed, and the priority is lower than `render`.|ReactNode |`-`|2.22.0|
|title|Column title|React.ReactNode **(Required)**|`-`|-|
|bodyCellStyle|Table body cell style|CSSProperties |`-`|-|
|className|ClassName of the column|string \| string[] |`-`|-|
|defaultFilters|To set default filters|string[] |`-`|-|
|filterDropdownProps|Configure properties of the filter popup box.|{ triggerProps?: [TriggerProps](trigger#trigger) } |`-`|-|
|filteredValue|To set filtered value, the value is the filtered value array|string[] |`-`|-|
|filters|Filter items, need to be used with `onFilter` or `onChange`|{text?: ReactNode;value?: any;[key: string]: any;}[] |`[]`|-|
|headerCellStyle|Table header cell style|CSSProperties |`-`|-|
|key|React key value, if not specified, the default value of `dataIndex` is taken|string \| number |`-`|-|
|sorter|Sorting function, if you want server-side sorting or adding more custom operations, set to true and use the `onChange` function for custom sorting|[SorterFn](#sorterfn) \| boolean \| { compare?: [SorterFn](#sorterfn); multiple?: number } |`-`|-|
|width|Column width|number \| string |`-`|-|
|filterDropdown|Custom filter popup box.|(props: {filterKeys?: string[];setFilterKeys?: (filterKeys: string[], callback?: Function) => void;confirm?: Function;}) => ReactNode |`-`|-|
|onCell|Set the event callback of the table body cell|(record, index) => [RowCallbackProps](#rowcallbackprops) |`-`|-|
|onFilter|Callback when filter changes|(value, row) => any |`-`|-|
|onFilterDropdownVisibleChange|Callback when the visible of filter popup changes|(visible: boolean) => void |`-`|-|
|onHeaderCell|Set the event callback of the table head cell|(column, index) => [RowCallbackProps](#rowcallbackprops) |`-`|-|
|render|Customize the content displayed in the cell|(col, item: T, index: number) => any |`-`|-|
### ComponentsProps
```js
export type ComponentsProps = {
table?: any;
header?: {
operations?: (nodes: {
selectionNode?: ReactNode;
expandNode?: ReactNode;
}) => {
name?: string;
node?: ReactNode;
width?: number;
}[];
wrapper?: any;
thead?: any;
row?: any;
th?: any;
cell?: any;
};
body?: {
operations?: (nodes: {
selectionNode?: ReactNode;
expandNode?: ReactNode;
}) => {
name?: string;
node?: ReactNode | ((record) => ReactNode); // 2.17.0
width?: number;
}[];
wrapper?: any;
tbody?: any;
row?: any;
td?: any;
cell?: any;
};
};
```
### SorterInfo
```js
export interface SorterInfo {
direction?: SortDirection;
field?: string | number;
sorterFn?: SorterFn;
priority?: number;
}
```
### SortDirection
```js
export declare type SortDirection = "descend" | "ascend";
```
### SorterFn
```js
export type SorterFn = (a: any, b: any) => number;
```
### RowCallbackProps
```js
export type RowCallbackProps = {
onClick?: (event) => void;
onDoubleClick?: (event) => void;
onContextMenu?: (event) => void;
onMouseEnter?: (event) => void;
onMouseLeave?: (event) => void;
onHandleSave?: (row) => void;
[name: string]: any;
};
```
### AvailableVirtualListProps
```js
export type AvailableVirtualListProps = Pick<
VirtualListProps,
| "height"
| "itemHeight"
| "threshold"
| "isStaticItemHeight"
| "scrollOptions"
| "onScroll"
| "wrapperChild"
>;
```
### Hide Pagination
If you want to hide pagination when the number of pages is less than or equal to one page, you can configure `pagination.hideOnSinglePage = true`. If you want to configure it globally,
You can configure the `tablePagination.hideOnSinglePage = true` of the `ConfigProvider` component.
### onRow
`onRow`, `onHeaderRow`, `onCell`, `onHeaderCell` have the same usage.
```js
{
return {
onClick: (event) => {}, // Click on the body row
onDoubleClick: (event) => {},
onContextMenu: (event) => {},
onMouseEnter: (event) => {},
onMouseLeave: (event) => {},
};
}}
onHeaderRow={(column, index) => {
return {
onClick: (event) => {}, // Click on the head row
onDoubleClick: (event) => {},
onContextMenu: (event) => {},
onMouseEnter: (event) => {},
onMouseLeave: (event) => {},
};
}}
/>
```
---
Index of all JGuang resources: https://jiguang132.com/llms.txt