- Fix FilterDropdownProps link in table/index.en-US.md - Fix FilterDropdownProps link in table/index.zh-CN.md
16 KiB
category | cols | type | title | cover |
---|---|---|---|---|
Components | 1 | Data Display | Table | https://gw.alipayobjects.com/zos/alicdn/f-SbcX2Lx/Table.svg |
A table displays rows of data.
When To Use
- To display a collection of structured data.
- To sort, search, paginate, filter data.
How To Use
Specify dataSource
of Table as an array of data.
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} />;
API
Table
Property | Description | Type | Default | Version |
---|---|---|---|---|
bordered | Whether to show all table borders | boolean | false | |
columns | Columns of table | ColumnsType[] | - | |
components | Override default table elements | TableComponents | - | |
dataSource | Data record array to be displayed | object[] | - | |
expandable | Config expandable content | expandable | - | |
footer | Table footer renderer | function(currentPageData) | - | |
getPopupContainer | The render container of dropdowns in table | (triggerNode) => HTMLElement | () => TableHtmlElement | |
loading | Loading status of table | boolean | Spin Props | false | |
locale | The i18n text including filter, sort, empty text, etc | object | Default Value | |
pagination | Config of pagination. You can ref table pagination config or full 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 | object | - | |
scroll | Whether the table can be scrollable, config | object | - | |
showHeader | Whether to show table header | boolean | true | |
showSorterTooltip | The header show next sorter direction tooltip. It will be set as the property of Tooltip if its type is object | boolean | Tooltip props | true | |
size | Size of table | default | middle | small |
default |
|
sortDirections | Supported sort way, could be ascend , descend |
Array | [ascend , descend ] |
|
sticky | Set sticky header and scroll bar | boolean | {offsetHeader?: number, offsetScroll?: number, getContainer?: () => HTMLElement} |
- | 4.6.0 (getContainer: 4.7.0) |
summary | Summary content | (currentData) => ReactNode | - | |
tableLayout | The table-layout attribute of table element | - | auto | fixed |
-fixed when header/columns are fixed, or using column.ellipsis |
|
title | Table title renderer | function(currentPageData) | - | |
onChange | Callback executed when pagination, filters or sorter is changed | function(pagination, filters, sorter, extra: { currentDataSource: [], action: paginate | sort | filter }) |
- | |
onHeaderRow | Set props on per header row | function(columns, index) | - | |
onRow | Set props on per row | function(record, index) | - |
onRow usage
Same as onRow
onHeaderRow
onCell
onHeaderCell
<Table
onRow={(record, rowIndex) => {
return {
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
};
}}
onHeaderRow={(columns, index) => {
return {
onClick: () => {}, // click header row
};
}}
/>
Column
One of the Table columns
prop for describing the table's columns, Column has the same API.
Property | Description | Type | Default | Version |
---|---|---|---|---|
align | The specify which way that column is aligned | left | right | center |
left |
|
className | The 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 |
- | |
editable | Whether column can be edited | boolean | false | |
ellipsis | The ellipsis cell content, not working with sorter and filters for now. tableLayout would be fixed when ellipsis is true or { showTitle?: boolean } |
boolean | {showTitle?: boolean } | false | showTitle: 4.3.0 |
filterDropdown | Customized filter overlay | ReactNode | (props: FilterDropdownProps) => ReactNode | - | |
filterDropdownVisible | Whether filterDropdown is visible |
boolean | - | |
filtered | Whether the dataSource is filtered |
boolean | false | |
filteredValue | Controlled filtered value, filter icon will highlight | string[] | - | |
filterIcon | Customized filter icon | ReactNode | (filtered: boolean) => ReactNode | - | |
filterMultiple | Whether multiple filters can be selected | boolean | true | |
filterMode | To specify the filter interface | 'menu' | 'tree' | 'menu' | 4.17.0 |
filterSearch | Whether to be searchable for filter menu | Boolean | false | 4.17.0 |
filters | Filter menu config | object[] | - | |
fixed | (IE not support) Set column to be fixed: true (same as left) 'left' 'right' |
boolean | string | false | |
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 | function(text, record, index) {} | - | |
responsive | The list of breakpoints at which to display this column. Always visible if not set. | Breakpoint[] | - | 4.2.0 |
shouldCellUpdate | Control cell render logic | (record, prevRecord) => boolean | - | 4.3.0 |
showSorterTooltip | If header show next sorter direction tooltip, override showSorterTooltip in table |
boolean | Tooltip props | true | |
sortDirections | Supported sort way, override sortDirections in Table , could be ascend , descend |
Array | [ascend , descend ] |
|
sorter | Sort function for local sort, see 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 | - | |
title | Title of this column | ReactNode | ({ sortOrder, sortColumn, filters }) => ReactNode | - | |
width | Width of this column (width not working?) | string | number | - | |
onCell | Set props on per cell | function(record, rowIndex) | - | |
onFilter | Function that determines if the row is displayed when filtered | function(value, record) => boolean | - | |
onFilterDropdownVisibleChange | Callback executed when filterDropdownVisible is changed |
function(visible) {} | - | |
onHeaderCell | Set props on per header cell | function(column) | - |
ColumnGroup
Property | Description | Type | Default |
---|---|---|---|
title | Title of the column group | ReactNode | - |
pagination
Properties for pagination.
Property | Description | Type | Default |
---|---|---|---|
position | Specify the position of Pagination , could betopLeft | topCenter | topRight |bottomLeft | bottomCenter | bottomRight |
Array | [bottomRight ] |
More about pagination, please check Pagination
.
expandable
Properties for expandable.
Property | Description | Type | Default | Version |
---|---|---|---|---|
childrenColumnName | The column contains children to display | string | children | |
columnWidth | Set the width of the expand column | string | number | - | |
defaultExpandAllRows | Expand all rows initially | boolean | false | |
defaultExpandedRowKeys | Initial expanded row keys | string[] | - | |
expandedRowClassName | Expanded row's className | function(record, index, indent): string | - | |
expandedRowKeys | Current expanded row keys | string[] | - | |
expandedRowRender | Expanded container render for each row | function(record, index, indent, expanded): ReactNode | - | |
expandIcon | Customize row expand Icon. Ref example | function(props): ReactNode | - | |
expandIconColumnIndex | Customize expand icon column index. Not render when -1 |
number | - | |
expandRowByClick | Whether to expand row by clicking anywhere in the whole row | boolean | false | |
fixed | Whether the expansion icon is fixed. Optional true left right |
boolean | string | false | 4.16.0 |
indentSize | Indent size in pixels of tree data | number | 15 | |
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) | - |
fixed
- When set to true or
left
andexpandIconColumnIndex
is not set or is 0, enable fixed - When set to true or
right
andexpandIconColumnIndex
is set to the number of table columns, enable fixed
- When set to true or
rowSelection
Properties for row selection.
Property | Description | Type | Default | Version |
---|---|---|---|---|
checkStrictly | Check table row precisely; parent row and children rows are not associated | boolean | true | 4.4.0 |
columnTitle | Set the title of the selection column | ReactNode | - | |
columnWidth | Set the width of the selection column | string | number | 32px |
|
fixed | Fixed selection column on the left | boolean | - | |
getCheckboxProps | Get Checkbox or Radio props | function(record) | - | |
hideSelectAll | Hide the selectAll checkbox and custom selection | boolean | false | 4.3.0 |
preserveSelectedRowKeys | Keep selection key even when it removed from dataSource |
boolean | - | 4.4.0 |
renderCell | Renderer of the table cell. Same as render in column |
function(checked, record, index, originNode) {} | - | 4.1.0 |
selectedRowKeys | Controlled selected row keys | string[] | number[] | [] | |
selections | Custom selection config, 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) | - | |
onSelectNone | Callback executed when row selection is cleared | function() | - |
scroll
Property | Description | Type | Default |
---|---|---|---|
scrollToFirstRowOnChange | Whether to scroll to the top of the table when paging, sorting, filtering changes | boolean | - |
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' | string | number | true | - |
y | Set vertical scrolling, can also be used to specify the height of the scroll area, could be string or number | string | number | - |
selection
Property | Description | Type | Default |
---|---|---|---|
key | Unique key of this selection | string | - |
text | Display text of this selection | ReactNode | - |
onSelect | Callback executed when this selection is clicked | function(changeableRowKeys) | - |
Using in TypeScript
import { Table } from 'antd';
import { ColumnsType } from 'antd/es/table';
interface User {
key: number;
name: string;
}
const columns: ColumnsType<User> = [
{
key: 'name',
title: 'Name',
dataIndex: 'name',
},
];
const data: User[] = [
{
key: 0,
name: 'Jack',
},
];
export default () => (
<>
<Table<User> columns={columns} dataSource={data} />
/* JSX style usage */
<Table<User> dataSource={data}>
<Table.Column<User> key="name" title="Name" dataIndex="name" />
</Table>
</>
);
Here is the CodeSandbox for TypeScript.
Note
According to the React documentation, 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
.
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.
// primary key is uid
return <Table rowKey="uid" />;
// or
return <Table rowKey={record => record.uid} />;
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
How to hide pagination when single page or no data?
You can set hideOnSinglePage
with pagination
prop.
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 as workaround.
Also you can use the action from extra param to determine when return to first page.
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.
Why Table fully render when state change?
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.
How to handle fixed column display over the mask layout?
Fixed column use z-index
to make it over other columns. You will find sometime fixed columns also over your mask layout. You can set z-index
on your mask layout to resolve.