2016-08-15 07:54:01 +08:00
---
category: Components
cols: 1
2016-11-09 14:43:32 +08:00
type: Data Display
2016-08-15 07:54:01 +08:00
title: Table
2020-05-31 11:48:34 +08:00
cover: https://gw.alipayobjects.com/zos/alicdn/f-SbcX2Lx/Table.svg
2016-08-15 07:54:01 +08:00
---
2017-09-18 10:28:05 +08:00
A table displays rows of data.
2016-08-15 07:54:01 +08:00
2016-09-10 13:43:30 +08:00
## When To Use
2016-08-15 07:54:01 +08:00
2016-11-29 17:13:24 +08:00
- To display a collection of structured data.
- To sort, search, paginate, filter data.
2016-08-15 07:54:01 +08:00
2016-09-10 13:43:30 +08:00
## How To Use
2016-08-15 07:54:01 +08:00
2017-09-04 10:47:37 +08:00
Specify `dataSource` of Table as an array of data.
2016-08-15 07:54:01 +08:00
```jsx
2019-05-07 14:57:32 +08:00
const dataSource = [
{
key: '1',
name: 'Mike',
age: 32,
address: '10 Downing Street',
},
{
key: '2',
name: 'John',
age: 42,
address: '10 Downing Street',
},
];
const columns = [
{
title: 'Name',
dataIndex: 'name',
key: 'name',
},
{
title: 'Age',
dataIndex: 'age',
key: 'age',
},
{
title: 'Address',
dataIndex: 'address',
key: 'address',
},
];
< Table dataSource = {dataSource} columns = {columns} / > ;
2016-08-15 07:54:01 +08:00
```
## API
### Table
2019-11-20 17:46:50 +08:00
| Property | Description | Type | Default |
| --- | --- | --- | --- |
2020-01-17 17:23:48 +08:00
| tableLayout | [table-layout ](https://developer.mozilla.org/en-US/docs/Web/CSS/table-layout ) attribute of table element | - \| `auto` \| `fixed` | -< hr /> `fixed` when header/columns are fixed, or using `column.ellipsis` |
2020-06-17 23:18:14 +08:00
| bordered | Whether to show all table borders | boolean | false |
2020-06-02 14:27:12 +08:00
| columns | Columns of table | [ColumnsType ](#Column )\[] | - |
2019-11-20 17:46:50 +08:00
| components | Override default table elements | [TableComponents ](https://git.io/fANxz ) | - |
2020-04-28 16:14:38 +08:00
| dataSource | Data record array to be displayed | object\[] | - |
2019-11-20 17:46:50 +08:00
| expandable | Config expandable content | [expandable ](#expandable ) | - |
| footer | Table footer renderer | Function(currentPageData) | - |
2020-06-17 23:18:14 +08:00
| loading | Loading status of table | boolean\|[object ](/components/spin/#API ) ([more](https://github.com/ant-design/ant-design/issues/4544#issuecomment-271533135)) | false |
2019-11-20 17:46:50 +08:00
| locale | i18n text including filter, sort, empty text, etc | object | filterConfirm: 'Ok' < br > filterReset: 'Reset' < br > emptyText: 'No Data' < br > [Default ](https://github.com/ant-design/ant-design/issues/575#issuecomment-159169511 ) |
| pagination | Config of pagination. You can ref table pagination [config ](#pagination ) or full [`pagination` ](/components/pagination/ ) document, hide it by setting it to `false` | object | - |
| rowClassName | Row's className | Function(record, index):string | - |
| rowKey | Row's unique key, could be a string or function that returns a string | string\|Function(record):string | `key` |
| rowSelection | Row selection [config ](#rowSelection ) | object | null |
| scroll | Whether the table can be scrollable, [config ](#scroll ) | object | - |
2020-06-17 23:18:14 +08:00
| showHeader | Whether to show table header | boolean | true |
2019-11-20 17:46:50 +08:00
| size | Size of table | `default` \| `middle` \| `small` | `default` |
| summary | Summary content | (currentData) => ReactNode | - |
| title | Table title renderer | Function(currentPageData) | - |
2020-06-09 21:41:11 +08:00
| onChange | Callback executed when pagination, filters or sorter is changed | Function(pagination, filters, sorter, extra: { currentDataSource: [], action: `paginate` \| `sort` \| `filter` }) | - |
2019-11-20 17:46:50 +08:00
| onHeaderRow | Set props on per header row | Function(column, index) | - |
| onRow | Set props on per row | Function(record, index) | - |
| getPopupContainer | the render container of dropdowns in table | (triggerNode) => HTMLElement | `() => TableHtmlElement` |
2020-02-28 12:11:16 +08:00
| sortDirections | supported sort way, could be `'ascend'` , `'descend'` | Array | `['ascend', 'descend']` |
2020-06-17 23:18:14 +08:00
| showSorterTooltip | header show next sorter direction tooltip | boolean | true |
2016-08-15 07:54:01 +08:00
2018-02-08 14:25:49 +08:00
#### onRow usage
Same as `onRow` `onHeaderRow` `onCell` `onHeaderCell`
2018-02-08 14:14:46 +08:00
```jsx
< Table
2018-12-29 07:19:12 +08:00
onRow={(record, rowIndex) => {
2018-02-08 14:14:46 +08:00
return {
2020-04-01 18:59:41 +08:00
onClick: event => {}, // click row
onDoubleClick: event => {}, // double click row
onContextMenu: event => {}, // right button click row
onMouseEnter: event => {}, // mouse enter row
onMouseLeave: event => {}, // mouse leave row
2018-02-08 14:14:46 +08:00
};
2018-03-22 14:54:46 +08:00
}}
2020-04-01 18:59:41 +08:00
onHeaderRow={column => {
2018-02-08 14:14:46 +08:00
return {
2019-05-07 14:57:32 +08:00
onClick: () => {}, // click header row
2018-02-08 14:14:46 +08:00
};
2018-03-22 14:54:46 +08:00
}}
2018-02-08 14:14:46 +08:00
/>
```
2016-08-15 07:54:01 +08:00
### Column
2017-09-18 10:28:05 +08:00
One of the Table `columns` prop for describing the table's columns, Column has the same API.
2016-08-15 07:54:01 +08:00
2020-05-05 15:03:22 +08:00
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| align | specify which way that column is aligned | `left` \| `right` \| `center` | `left` | |
2020-05-12 12:44:49 +08:00
| ellipsis | ellipsis cell content, not working with sorter and filters for now.< br /> tableLayout would be `fixed` when `ellipsis` is `true` or `{ showTitle?: boolean }` . | boolean \| { showTitle?: boolean } | false | showTitle: 4.3.0 |
2020-05-05 15:03:22 +08:00
| className | className of this column | string | - | |
| colSpan | Span of this column's title | number | - | |
| dataIndex | Display field of the data record, support nest path by string array | string \| string\[] | - | |
| defaultFilteredValue | Default filtered values | string\[] | - | | |
| defaultSortOrder | Default order of sorted values | `ascend` \| `descend` | - | |
2020-06-13 14:26:29 +08:00
| filterDropdown | Customized filter overlay | ReactNode \| (props: [FilterDropdownProps ](https://git.io/fjP5h )) => ReactNode | - | |
2020-05-05 15:03:22 +08:00
| filterDropdownVisible | Whether `filterDropdown` is visible | boolean | - | |
2020-06-17 23:18:14 +08:00
| filtered | Whether the `dataSource` is filtered | boolean | false | |
2020-05-05 15:03:22 +08:00
| filteredValue | Controlled filtered value, filter icon will highlight | string\[] | - | |
2020-06-17 23:18:14 +08:00
| filterIcon | Customized filter icon | ReactNode\|(filtered: boolean) => ReactNode | false | |
| filterMultiple | Whether multiple filters can be selected | boolean | true | |
2020-05-05 15:03:22 +08:00
| filters | Filter menu config | object\[] | - | |
2020-06-17 23:18:14 +08:00
| fixed | (IE not support) Set column to be fixed: `true` (same as left) `'left'` `'right'` | boolean\|string | false | |
2020-05-05 15:03:22 +08:00
| key | Unique key of this column, you can ignore this prop if you've set a unique `dataIndex` | string | - | |
| render | Renderer of the table cell. The return value should be a ReactNode, or an object for [colSpan/rowSpan config ](#components-table-demo-colspan-rowspan ) | Function(text, record, index) {} | - | |
2020-05-09 20:40:12 +08:00
| responsive | The list of breakpoints at which to display this column. Always visible if not set. | [Breakpoint ](https://github.com/ant-design/ant-design/blob/015109b42b85c63146371b4e32b883cf97b088e8/components/_util/responsiveObserve.ts#L1 )\[] | - | 4.2.0 |
2020-06-12 22:14:42 +08:00
| shouldCellUpdate | Control cell render logic | (record, prevRecord) => boolean | - | 4.3.0 |
2020-05-05 15:03:22 +08:00
| sorter | Sort function for local sort, see [Array.sort ](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort )'s compareFunction. If you need sort buttons only, set to `true` | Function\|boolean | - | |
| sortOrder | Order of sorted values: `'ascend'` `'descend'` `false` | boolean\|string | - | |
| sortDirections | supported sort way, override `sortDirections` in `Table` , could be `'ascend'` , `'descend'` | Array | `['ascend', 'descend']` | |
| title | Title of this column | ReactNode\|({ sortOrder, sortColumn, filters }) => ReactNode | - | |
| width | Width of this column ([width not working?](https://github.com/ant-design/ant-design/issues/13825#issuecomment-449889241)) | string\|number | - | |
| onCell | Set props on per cell | Function(record, rowIndex) | - | |
| onFilter | Callback executed when the confirm filter button is clicked | Function | - | |
| onFilterDropdownVisibleChange | Callback executed when `filterDropdownVisible` is changed | function(visible) {} | - | |
| onHeaderCell | Set props on per header cell | Function(column) | - | |
2020-06-17 23:18:14 +08:00
| showSorterTooltip | header show next sorter direction tooltip, override `showSorterTooltip` in table | boolean | true | |
2016-08-15 07:54:01 +08:00
2016-11-22 10:11:12 +08:00
### ColumnGroup
2019-11-20 17:46:50 +08:00
| Property | Description | Type | Default |
| -------- | ------------------------- | ----------------- | ------- |
| title | Title of the column group | string\|ReactNode | - |
2016-11-22 10:11:12 +08:00
2018-03-02 12:00:28 +08:00
### pagination
Properties for pagination.
2020-03-27 15:48:42 +08:00
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| position | specify the position of `Pagination` , could be `topLeft` \| `topCenter` \| `topRight` \|`bottomLeft` \| `bottomCenter` \| `bottomRight` | Array | `['bottomRight']` |
2018-03-02 12:00:28 +08:00
More about pagination, please check [`Pagination` ](/components/pagination/ ).
2019-11-15 14:35:25 +08:00
### expandable
Properties for expandable.
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| childrenColumnName | The column contains children to display | string\[] | children |
2020-06-17 23:18:14 +08:00
| defaultExpandAllRows | Expand all rows initially | boolean | false |
2019-11-15 14:35:25 +08:00
| defaultExpandedRowKeys | Initial expanded row keys | string\[] | - |
2020-02-28 11:09:17 +08:00
| expandIcon | Customize row expand Icon. Ref [example ](https://codesandbox.io/s/fervent-bird-nuzpr ) | Function(props):ReactNode | - |
2020-03-03 22:52:58 +08:00
| expandIconColumnIndex | Customize expand icon column index | number | - |
2019-11-15 14:35:25 +08:00
| expandedRowKeys | Current expanded row keys | string\[] | - |
| expandedRowRender | Expanded container render for each row | Function(record, index, indent, expanded):ReactNode | - |
2020-06-17 23:18:14 +08:00
| expandRowByClick | Whether to expand row by clicking anywhere in the whole row | boolean | false |
2019-11-15 14:35:25 +08:00
| indentSize | Indent size in pixels of tree data | number | 15 |
2019-11-20 17:46:50 +08:00
| rowExpandable | Enable row can be expandable | (record) => boolean | - |
| onExpand | Callback executed when the row expand icon is clicked | Function(expanded, record) | - |
| onExpandedRowsChange | Callback executed when the expanded rows change | Function(expandedRows) | - |
2019-11-15 14:35:25 +08:00
2016-08-15 07:54:01 +08:00
### rowSelection
2017-09-18 10:28:05 +08:00
Properties for row selection.
2016-08-15 07:54:01 +08:00
2020-02-29 23:11:02 +08:00
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| columnWidth | Set the width of the selection column | string\|number | `60px` | 4.0 |
| columnTitle | Set the title of the selection column | string\|React.ReactNode | - | 4.0 |
| fixed | Fixed selection column on the left | boolean | - | 4.0 |
| getCheckboxProps | Get Checkbox or Radio props | Function(record) | - | 4.0 |
2020-06-17 23:18:14 +08:00
| hideSelectAll | Hide the selectAll checkbox and custom selection | boolean | false | 4.3 |
2020-06-04 17:08:20 +08:00
| preserveSelectedRowKeys | Keep selection `key` even when it removed from `dataSource` | boolean | - | 4.4 |
2020-02-29 23:11:02 +08:00
| renderCell | Renderer of the table cell. Same as `render` in column | Function(checked, record, index, originNode) {} | - | 4.1 |
2020-06-04 17:08:20 +08:00
| selectedRowKeys | Controlled selected row keys | string\[]\|number[] | \[] | |
| selections | Custom selection [config ](#rowSelection ), only displays default selections when set to `true` | object\[]\|boolean | - | |
| type | `checkbox` or `radio` | `checkbox` \| `radio` | `checkbox` | |
| onChange | Callback executed when selected rows change | Function(selectedRowKeys, selectedRows) | - | |
| onSelect | Callback executed when select/deselect one row | Function(record, selected, selectedRows, nativeEvent) | - | |
| onSelectAll | Callback executed when select/deselect all rows | Function(selected, selectedRows, changeRows) | - | |
| onSelectInvert | Callback executed when row selection is inverted | Function(selectedRowKeys) | - | |
2017-02-23 19:29:47 +08:00
2019-09-26 11:31:28 +08:00
### scroll
2019-11-20 17:46:50 +08:00
| Property | Description | Type | Default |
| --- | --- | --- | --- |
2020-01-19 16:57:04 +08:00
| x | Set horizontal scrolling, can also be used to specify the width of the scroll area, could be number, percent value, true and ['max-content' ](https://developer.mozilla.org/zh-CN/docs/Web/CSS/width#max-content ) | number \| true | - |
| y | Set vertical scrolling, can also be used to specify the height of the scroll area, could be number | number | - |
2019-11-20 17:46:50 +08:00
| scrollToFirstRowOnChange | Whether to scroll to the top of the table when paging, sorting, filtering changes | boolean | - |
2019-09-26 11:31:28 +08:00
2017-02-23 19:29:47 +08:00
### selection
2019-11-20 17:46:50 +08:00
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| key | Unique key of this selection | string | - |
2020-06-13 14:26:29 +08:00
| text | Display text of this selection | string\|ReactNode | - |
2019-11-20 17:46:50 +08:00
| onSelect | Callback executed when this selection is clicked | Function(changeableRowKeys) | - |
2016-08-15 07:54:01 +08:00
2017-01-11 19:52:43 +08:00
## Using in TypeScript
2018-11-09 18:04:47 +08:00
```tsx
2017-01-11 19:52:43 +08:00
import { Table } from 'antd';
2020-06-02 14:27:12 +08:00
import { ColumnsType } from 'antd/es/table';
2017-01-11 19:52:43 +08:00
2019-06-27 14:17:08 +08:00
interface User {
2017-01-11 19:52:43 +08:00
key: number,
name: string;
}
2020-06-02 14:27:12 +08:00
const columns: ColumnsType< User > [] = [{
2017-01-11 19:52:43 +08:00
key: 'name',
title: 'Name',
dataIndex: 'name',
}];
2019-06-27 14:17:08 +08:00
const data: User[] = [{
2017-01-11 19:52:43 +08:00
key: 0,
name: 'Jack',
}];
2019-06-27 14:17:08 +08:00
class UserTable extends Table< User > {}
2017-01-11 19:52:43 +08:00
< UserTable columns = {columns} dataSource = {data} / >
// Use JSX style API
2019-06-27 14:17:08 +08:00
class NameColumn extends Table.Column< User > {}
2017-01-11 19:52:43 +08:00
< UserTable dataSource = {data} >
< NameColumn key = "name" title = "Name" dataIndex = "name" / >
< / UserTable >
2018-11-09 18:04:47 +08:00
// after TypeScript 2.9 can write like this
// https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-9.html#generic-type-arguments-in-jsx-elements
2019-06-27 14:17:08 +08:00
< Table < User > columns={columns} dataSource={data} />
< Table < User > dataSource={data}>
< Table.Column < User > key="name" title="Name" dataIndex="name" />
2018-11-09 18:04:47 +08:00
< / Table >
2017-01-11 19:52:43 +08:00
```
2016-08-15 07:54:01 +08:00
## Note
2019-10-08 22:06:50 +08:00
According to the [React documentation ](https://facebook.github.io/react/docs/lists-and-keys.html#keys ), every child in an array should be assigned a unique key. The values inside the Table's `dataSource` and `columns` should follow this rule. By default, `dataSource[i].key` will be treated as the key value for `dataSource` .
2016-08-15 07:54:01 +08:00
2018-05-21 23:42:57 +08:00
![console warning ](https://os.alipayobjects.com/rmsportal/luLdLvhPOiRpyss.png )
2016-08-15 07:54:01 +08:00
2019-10-08 22:06:50 +08:00
If `dataSource[i].key` is not provided, then you should specify the primary key of dataSource value via `rowKey` , as shown below. If not, warnings like the one above will show in browser console.
2016-08-15 07:54:01 +08:00
```jsx
// primary key is uid
return < Table rowKey = "uid" / > ;
// or
2020-04-01 18:59:41 +08:00
return < Table rowKey = {record = > record.uid} />;
2016-08-15 07:54:01 +08:00
```
2019-11-15 14:35:25 +08:00
## Migrate to v4
Table removes `onRowClick` , `onRowDoubleClick` , `onRowMouseEnter` , `onRowMouseLeave` and some other api which is already deprecated in v3. If you only use api listing in official document, that's OK.
Besides, the breaking change is changing `dataIndex` from nest string path like `user.age` to string array path like `['user', 'age']` . This help to resolve developer should additional work on the field which contains `.` .
## FAQ
2020-04-01 18:59:41 +08:00
### How to hide pagination when single page or not data?
2019-11-15 14:35:25 +08:00
You can set `hideOnSinglePage` with `pagination` prop.
2020-04-01 18:59:41 +08:00
### Table will return to first page when filter data.
Table total page count usually reduce after filter data, we defaultly return to first page in case of current page is out of filtered results.
You may need to keep current page after filtering when fetch data from remote service, please check [this demo ](https://codesandbox.io/s/yuanchengjiazaishuju-ant-design-demo-7y2uf ) as workaround.
2020-04-09 10:52:02 +08:00
2020-06-09 21:41:11 +08:00
Also you can use the action from extra param to determine when return to first page.
2020-04-09 10:52:02 +08:00
### Why Table pagination show size changer?
In order to improve user experience, Pagination show size changer by default when `total >= 50` since `4.1.0` . You can set `showSizeChanger=false` to disable this feature.
2020-05-03 16:10:37 +08:00
### Why Table fully render when state change?
2020-05-05 15:03:22 +08:00
Table can not tell what state used in `columns.render` , so it always need fully render to avoid sync issue. You can use `column.shouldCellUpdate` to control render.