Show · Table
Table
Tables are used to present structured data content, usually accompanied by the ability to manipulate the data (sort, search, paginate...).

How to Use

Into the header. columns And data. DataSource To render.
Please provide a "key" for each data item in the dataSource that is different from the value of the other data items, or use the row Key parameter to specify an attribute name as the primary key, alternative row operation functions such as row selection and expansion of the table.

Demos

Basic Table

For tables, the two most basic parameters are dataSource and columns, the former is the data item, the latter is the configuration of each column, both are array types.

JSX Writing

You can also use JSX syntax definitions columns, note that Table only supports columns JSX syntax definition. You cannot use any component package Table.Column.
Note: JSX-written tables are not supported the parameter Resizable.
Notice
When columns are written in JSX, please do not use it at the same time as the configuration method; if used at the same time, only the configuration method will take effect, and no aggregation operation will be performed.

Row Selection Operation

This feature can be turned on by passing in rowSelection.
  • Click the selection box in the header, and all rows in the dataSource that are not in the state of disabled will be selected. The callback function for selecting all rows is onSelectAll;
  • Clicking on the row selection box will select the current row. Its callback function is onSelect;
Note: Be sure to provide a "key" for each row of data that is different from other row values, or use the rowKey parameter to specify a property name as the primary key.

Custom Rendering

Users can use Column.render to customize the rendering of a column of cells, which is suitable for rendering more complex cell content.

Table With Pagination

Table paging currently supports two modes: controlled and uncontrolled.
  • In controlled mode, the paging state is passed entirely externally, depending on whether the pagination .currentPage field is passed. In general, the controlled mode is suitable for remotely pulling data and rendering.
  • In uncontrolled mode, Table passes the incoming dataSource length as total to the Pagination component by default, and of course you can also pass a total field to overwrite the value of the Table component, but we do not recommend users to pass this field in uncontrolled paging mode.
Note: The custom pagination.total field passed in uncontrolled conditions is supported only after version 0.25.0.

Pull Remote Data

Under normal circumstances, the data is often not obtained at one time. We will retrieve the data from the interface when clicking on the page number, filter or sort button. In this case, please use Controlled mode To handle pagination. The user needs to pass in the pagination.currentPage field, where the rendering of the pagination component depends entirely on the incoming pagination object.
Notice
1. When pagination is an object type, literal is not recommended because it causes the table to render to its original state (it looks like the pager is not working). Please try to define reference type parameters outside the render method. If hooks are used, please use useMemo or useState for storage.
2. In the controlled mode, Table will not paginate dataSource, please pass in current page data to dataSource

Fixed Column or Head

You can fix the column by setting the Fixed attribute of the column and scroll.x, and fix the header by setting scroll.y.
  • It is recommended to specify scroll.x as a fixed value or percentage greater than the width of the table. If it is a fixed value, set it to >= the sum of all fixed column widths + the sum of all table column widths.
  • Make sure that all elements inside the table do not affect the height of the cells after rendering (e.g. containing unloaded pictures, etc.). In this case, give the stator element a definite height to ensure that the left and right Fixed columns of cells are not deranged.
  • If the column header is not aligned with the content or there is a column duplication or when the fixed column fails, specify the width width of the fixed column, if still not effective, try to recommend leaving a column with no width to accommodate the elastic layout, or check for ultra-long continuous fields to destroy the layout.
The header can be fixed to the top of the page with the sticky property. v2.21 version support. When passing top, you can control the distance from the scroll container.
标题
​
大小
所有者
更新日期
No Result

Table Header With Sorting and Filtering Function

Filters and sorting controls are integrated inside the table, and users can pass in the sorter display of the sorter open header by passing filters in Column and the filter control display of the onFilter open header.
Note: Be sure to provide a "key" for each row of data that is different from other row values, or use the rowKey parameter to specify a property name as the primary key.

Custom Filter Item Rendering

Since the 1.1.0 version, it is supported to pass in renderFilterDropdownItem to customize the rendering method of each filter item.
This method accepts an Object input parameter, and the meaning of each attribute is as follows:
  • onChange: e => void current filter item selection/reverse selection event;
  • text: ReactNode copy of the current screening item;
  • value: any the value of the current filter item;
  • checked: boolean whether the current filter item has been selected;
  • filteredValue: any[] all currently filtered values;
  • level: number is the level of the current filter item, if it is a nested filter item, the value will be >= 1;
  • filterMultiple: boolean whether the current filter item is multi-select.

A Table That Can Be Expanded

Note
1. Since version `0.27.0`, the unfold button will be rendered in the same cell as the first column, and you can open a separate column of rendering by passing in `hideExpandedColumn = `.
2. Be sure to provide a "key" for each row of data that is different from the other row values, or use the rowKey parameter to specify an attribute name as the primary key.

A Common Table That Can Be Expanded

If you need to render a table that can be expanded, in addition to the need to pass expandedRowRender In addition to this method, you must specify rowKey(by default key), Table will be based on rowKey Gets a row unique identifier.
  • If rowKey is a Function, the result of rowKey(record) is taken as the row unique ID
  • If rowKey is a string type, you take record[rowKey] as the row unique ID

The Unfold Button Is Rendered In a Separated Column

Version: >= 0.27.0
By default, the expansion button will be rendered in the same cell as the first copy, and you can enter hideExpandedColumn={false} to render as a separate column:

Turn Off Rendering of Expandable Button of a Row

Version: > = 0.27.0
You can pass the row Expandable method, enter the reference as record, and determine whether the return value is false to close the rendering of the expandable button on a row.

Tree Data Display

Version: > = 0.27.0
The table supports the display of tree data and is automatically displayed as a tree table when there are children fields in the data. If you do not need or use other fields, you can configure it with the childrenRecordName. In addition, you can control the indent width of each layer by setting indent Size.
Note: Be sure to provide a "key" for each row of data that is different from the other row values, or use the rowKey parameter to specify a property name as the primary key.

Simple example of tree data

Rows of Interchangeable Tree Data

Version: > = 0.27.0
You can do row switching by changing the order of the dataSource elements.

Tree Selection

Version: >=0.27.0
By default, the row selection of the table is independent. You can simulate a tree selection by defining selectedRowKeys.

Custom Row or Cell Events and Properties

  • The incoming onRow / onHeaderRow can define the native event or property of a table or table header line.
  • The incoming Column.onCell / Column.onHeaderCell can define a table or header cell native event or property.
In principle, the properties or events supported on tr / td / th can be defined. For example:
  • The tr at the head of the watch defines onMouseEnter / onMouseLeave
  • The tr of the table defines className
  • The third line of the table defines onClick.

Zebra Pattern Table

Use OnRow to set a background color for each row to create a zebra stripped table.

Column Ellipsis

Use ellipsis to make cells automatically clipped. v2.34.0 support.
Set ellipsis.showTitle to false to hide the default native HTML title. With column.render you can customize the content prompt.

Resizable Column

Version > = 0.15.0

Basic Resizable Column

For some columns with more content, you can choose to turn on the telescopic column function and pull and pull at the head to realize the real-time change of column width.
But you need to pay attention to some parameters:
  • resizable is set to true or an object
  • Any column in columns that requires a telescopic function should specify the widthfield (if not passed, the column does not have a telescopic function and its column width will be automatically adjusted by the browser)
  • column.resize can take effect after resizable is enabled. After setting to false, the column no longer supports scaling. v2.42 support
When used with fixed columns, you need to specify a column without setting the width
It is not recommended to use it with scroll.x at the same time. scroll.x specifies that the table has a width range, and stretching columns will expand the column width, which may cause the table to be misaligned

Advanced Telescopic Columns

resizable can also be an object, including three event methods:
  • onResize
  • onResizeStart
  • onResizeStop
These three callback will be triggered on changing column width, start changing column width and stop changing column width respectively. Developers can choose to modify the column at this time, such as adding a vertical line effect when dragging, as shown below.
The CSS style definition used in this example:

Drag Sorting

With custom elements, we can integrate react-dnd To implement drag and drop sorting.
The CSS styles used in this example are:

Table Grouping

For some tables whose data needs to be displayed in groups, you can pass in groupBy to define the grouping rules, and use renderGroupSection to define the rendering of the grouping table header.
Note: Be sure to provide a "key" for each row of data that is different from other row values, or use the rowKey parameter to specify a property name as the primary key.

Virtualized Table

Virtualization can be used for scenes that need to render large-scale data. You can enable this feature by configuring the virtualized parameter. have to be aware of is:
  • Must pass scroll.y (number) andstyle.width (number);
  • Need to pass the height of each line virtualized.itemSize (when not transmitting, the normal line height defaults to 56, and the group head line height defaults to 56), can be of the following types:
    • number
    • (index, { sectionRow?: boolean, expandedRow?: boolean }) => number
  • Table grouping virtualization requires version >= 0.37.0.
The following is an example of rendering 1000 pieces of data.

Infinite Scroll

Based on the virtualization feature, we can achieve infinite scroll loading data by passing in virtualized.onScroll.

Controlled Dynamic Tables

Fully custom rendering

Version: >=0.34.0
Generally, you can use Column.render, but you can also passColumn.useFullRender = true to enable full custom rendering mode. At this time, the components such as checkbox button, expand button, indent will be Pass through to the Column.title andColumn.render methods, you can further define the rendering method of the header and cell content.
The input parameters accepted by Column.title are:
Column.render The fourth input parameter is:
The example below renders the checkbox and content into the same cell and header.

Header Merge

Version: >=1.1.0
Users can use the header merge function to group the header. The header merge can be combined with fixed column, virtualization, data grouping, column scaling and other functions. It also supports JSX or configurable writing.

Combined Header Configuration Writing

Merge Header JSX Writing

colSpan and rowSpan

  • In addition to merging the headers by writing children, you can merge the headers by setting column.colSpan.
  • Table supports row/column merging. When the cell attribute colSpan or rowSpan in render is set to 0, the set table will not be rendered.

API Reference

Table

PropertiesInstructionsTypeDefaultVersion
borderedWhether to display outer and column bordersbooleanfalse
classNameOutermost style namestring
clickGroupedRowToExpandGroup content expands or collapses when the group header row is clickedboolean0.29.0
columnsFor a configuration description of the table column, see ColumnColumn [][]
dataSourceDataRecordType[][]
defaultExpandAllRowsAll rows are expanded by defaultbooleanfalse
defaultExpandAllGroupRowsAll grouped rows are expanded by defaultbooleanfalse1.30.0
defaultExpandedRowKeysDefault expansion of row key arrayArray <*>[]
emptyContent displayed when there is no dataReactNodeReactNode'No data yet. '
expandCellFixedWhether the column of the expansion icon is fixed or not, the same value as the fixed value in Columnboolean|stringfalse
expandIconCustom expansion icon, hidden when it is falseboolean
|ReactNode
| (expanded: boolean) => ReactNode
expandedRowKeysExpanded rows, the row expansion function will be controlled when this parameter is introduced.(string | number)[]
expandedRowRenderExtra unfolding lines(record: object, index: number, expanded: boolean) => ReactNode
expandAllRowsAll rows are expandedbooleanfalse1.30.0
expandAllGroupRowsAll grouped rows are expandedbooleanfalse1.30.0
expandRowByClickExpand row when click rowbooleanfalse1.31.0
footerEnd of formstring
|ReactNode
|(pageData: object) => string|ReactNode
groupByGrouping basis, generally a method of a key name or a return value of a string or number in the dataSource elementstring|number
|(record: any) => string|number		0.29.0
hideExpandedColumnWhether to hide the expansion button column and turn off the rendering of the expansion button when it is turned onbooleantrue
indentSizeindent size of TableCellnumber20
loadingTable is loading or notbooleanfalse
paginationPaging component configurationboolean|TablePaginationPropstrue
prefixClsStyle name prefixstring
renderGroupSectionHeader rendering method(groupKey?: string | number, group?: string[] | number[]) => ReactNode0.29.0
renderPaginationCustomize the rendering method of pagination.(paginationProps?: TablePaginationProps) => ReactNode1.13.0
resizableWhether to turn on the telescopic column function, the column that needs to be telescopic must provide the value of widthboolean|Resizablefalse
rowExpandableWhether the row can be expanded, turning off the rendering of the expandable button when the value is false(record: RecordType): => boolean() => true0.27.0
rowKeyThe value of the table row key, which can be a string or a function.string | (record: RecordType) => string'key'
rowSelectionSee rowSelectionobjectnull
scrollWhether the table is scrollable, configure the width or height of the scroll area, see scrollobject-
showHeaderDoes it show the header?booleantrue
sizeTable size, will effect the padding of the rows"default"|"middle"|"small""default"1.0.0
stickyfixed headerboolean | { top: number }false2.21.0
titleTable Titlestring
|ReactNode
|(pageData: RecordType[]) => string|ReactNode
virtualizedVirtualization settingsVirtualizedfalse0.33.0
virtualized.itemSizeRow heightnumber|(index: number) => number560.33.0
virtualized.onScrollVirtualization scroll callback method( scrollDirection?: 'forward' | 'backward', scrollOffset?: number, scrollUpdateWasRequested?: boolean ) => void0.33.0
onChangeTrigger when paging, sorting, filtering changes({ pagination: TablePaginationProps,
filters: Array<*>, sorter: object, extra: any }) => void
onExpandTrigger when clicking on the row expansion icon(expanded: boolean, record: RecordType, DOMEvent: MouseEvent) => voidThe third parameter DOMEvent requires version >=0.28.0
onExpandedRowsChangeTriggers when unfolding row changes(rows: RecordType[]) => void
onGroupedRowSimilar to onRow, but this parameter is used to define the row attribute of the grouping header alone(record: RecordType, index: number) => object0.29.0
onHeaderRowSet the header row property, and the returned object is merged to the header line(columns: Column[], index: number) => object
onRowSet the row property, and the returned object is merged to the table row(record: RecordType, index: number) => object
Some of the type definitions used above:
RecordType is a generic parameter of Table and Column, and the default is object type. You can use RecordType like this:

onRow/onHeaderRow Usage

Also in column.onCell column.onHeaderCell Properties or events supported by td / th can also be returned.

Column

ParametersInstructionsTypeDefaultVersion
alignSetting the alignment of columns'left '| 'right '| 'center''left'
childrenSettings for sub-columns when the header is mergedColumn[]
classNameColumn style namestring
colSpanWhen header columns merge, set to 0, do not rendernumber
dataIndexThe key corresponding to the column data in the data item. It is required when using sorter or filter.string
defaultFilteredValueDefault value of the filter, the filter state of the external control column with a value of the screened value arrayany[]2.5.0
defaultSortOrderThe default value of sortOrder, one of 'ascend'|'descend'|falseboolean| stringfalse1.31.0
directionRTL, LTR direction, the default value is equal to ConfigProvider direction, you can configure the direction of the Table separately here'ltr' | 'rtl'2.31.0
ellipsisEllipsis Text, table-layout will automatically switch to fixed after it is turned onboolean| { showTitle: boolean }false2.34.0
filterChildrenRecordWhether the child data needs to be filtered locally. If this function is enabled, if the child meets the filtering criteria, the parent will retain it even if it does not meet the criteria.boolean0.29.0
filterDropdownYou can customize the filter menu. This function is only responsible for rendering the layer and needs to write a variety of interactions.ReactNode
filterDropdownPropsProps passing to Dropdown, see more in Dropdown APIobject
filterDropdownVisibleVisible of Dropdown, see more in Dropdown APIboolean
filterIconCustom filter iconboolean|ReactNode|(filtered: boolean) => ReactNode
filterMultipleWhether to choose morebooleantrue
filteredValueControlled property of the filter, the filter state of the external control column with a value of the screened value arrayany[]
filtersFilter menu items for the headerFilter[]
fixedWhether the column is fixed, optional true (equivalent to left) 'left' 'right'boolean|stringfalse
keyThe key required by React, if a unique dataIndex has been set, can ignore this propertystring
renderA rendering function that generates complex data, the parameters are the value of the current row, the current row data, the row index, and the table row / column merge can be set in return object(text: any, record: RecordType, index: number, { expandIcon?: ReactNode, selection?: ReactNode, indentText?: ReactNode }) => React|object
renderFilterDropdownItemCustomize the rendering method of each filter item. For usage details, see Custom Filter Item Rendering({ value: any, text: any, onChange: Function, level: number, ...otherProps }) => ReactNode-1.1.0
resizeWhether to enable resize mode, this property will take effect only after Table resizable is enabledboolean2.42.0
sortChildrenRecordWhether to sort child data locallyboolean0.29.0
sortOrderThe controlled property of the sorting, the sorting of this control column can be set to 'ascend'|'descended '|falsebooleanfalse
sorterSorting function, local sorting uses a function (refer to the compreFunction of Array.sort), requiring a server-side sorting can be set to trueboolean|(r1: RecordType, r2: RecordType) => numbertrue
titleColumn header displays text. When a function is passed in, title will use the return value of the function; when other types are passed in, they will be aggregated with sorter and filter. It needs to be used with useFullRender to obtain parameters such as filter in the function typestring | ReactNode|({ filter: ReactNode, sorter: ReactNode, selection: ReactNode }) => ReactNode.Function type requires 0.34.0
useFullRenderWhether to completely customize the rendering, see Full Custom Rendering for usage details, enabling this feature will cause a certain performance lossbooleanfalse0.34.0
widthColumn widthstring | number
onCellSet cell properties(record: RecordType, rowIndex: number) => object
onFilterDetermine the running function of the filter in local mode(filteredValue: any, record: RecordType) => boolean
onFilterDropdownVisibleChangeA callback when a custom filter menu is visible(visible: boolean) => void
onHeaderCellSet the head cell property(column: RecordType, columnIndex: number) => object
Some of the type definitions used above:

rowSelection

ParametersInstructionsTypeDefaultVersion
classNameStyle name listedstring
disabledDisabled Checkbox in Table header or not.booleanfalse0.32.0
fixedSecure the selection box column to the left.booleanfalse
getCheckboxPropsDefault property configuration for the selection box(record: RecordType) => object
hiddenHide selection column or notbooleanfalse0.34.0
selectedRowKeysSpecifies the key array of the selected item, which needs to work with onChangestring []
widthCustom list selection box widthstringnumber
onChangeA callback in the event of a change in the selected item. The first parameter will save the row keys selected last time, even if you do paging control or update the dataSource FAQ(selectedRowKeys: number[]|string[], selectedRows: RecordType[]) => void
onSelectCallback when the user manually clicks the selection box of a row(record: RecordType, selected: boolean, selectedRows: RecordType[], nativeEvent: MouseEvent) => void
onSelectAllThe user manually clicks the callback of the header selection box, and all optional rows in the dataSource will be selected/unselected(selected: boolean, selectedRows: RecordType[], changedRows: RecordType[]) => void

scroll

ParametersInstructionsTypeDefaultVersion
scrollToFirstRowOnChangeWhether to automatically scroll to the top of the table after paging, sorting, and filtering changesbooleanfalse1.1.0
xSet the width of the horizontal scroll area, which can be pixel value, percentage, or 'max-content'string|number
ySet the height of the vertical scroll area, which can be a pixel valuenumber

pagination

Page-turning component configuration. Pagination suggests not to use literal value.
Note: After pagination.onChange is set, Table onChange no longer responds to pagination changes.
ParametersInstructionsTypeDefaultVersion
currentPageCurrent page numbernumber-
defaultCurrentPageDefault current page numbernumber1>=1.1.0
formatPageTextPage-turning area copywriting custom formatting, pass false to close copywriting display; This item affects the copy display on the left of the page turning area of the form. It is different from the showTotal parameter of thePagination component.boolean| ({ currentStart: number, currentEnd: number, total: number }) => string|ReactNodetrue0.27.0
pageSizeNumber of entries per pagenumber10
positionLocation'bottom '|'top '|'both''bottom'
totalTotal number of entriesnumber0>=0.25.0
For other configurations, see Pagination

Resizable

The parameters of the resizable object type, which mainly include event methods when the table column is scaled. These event methods can return an object that merges with the final column.
ParametersInstructionsTypeDefault
onResizeTriggers when the table column changes its width(column: Column) => Column
onResizeStartTriggers when the table column starts to change the width.(column: Column) => Column
onResizeStopTriggers when the table column stops changing the width(column: Column) => Column

Methods

Some internal methods provided by Table can be accessed through ref:
ParametersInstructionsVersion
getCurrentPageData()Returns the data object of the current page: { dataSource: RecordType[], groups: Map<{groupKey: string, recordKeys: Set<string>}> }0.37.0

Accessibility

ARIA

  • The role of the table is grid, and the role of the tree table is treegrid
  • the row's role is row, and the cell's role is gridcell
  • Added aria-rowcount and aria-colcount attributes to the table to indicate the number of rows and columns
  • The row has added aria-rowindex to indicate which row it currently belongs to, and the first row is 1
  • The row of the tree table has aria-level representing the tree level of the current row, the first level is 1
  • Expandable table rows have the aria-expanded attribute, indicating whether the current row is expanded
  • The new aria-colindex of the cell indicates which column the current grid belongs to, and the first column is 1
  • Added aria-label to column filter and sort buttons, and added aria-label attribute to row select buttons

RTL/LTR

Content Guidelines

  • Table title
    • The title of the table should clearly make the user perceive the purpose of the table;
    • Add descriptions to complex tables to provide users with more contextual information about the table;
    • use sentence case;
  • Column headers
    • Keep column headings concise, it is recommended to use 1-2 words as column headings;
    • When the column header is long, it is recommended to display it in 2 lines, and the remaining text is abbreviated and displayed completely in the Tooltip;
    • Adopt the capitalization rules of Sentence case;
    • Use sentence case for column headings;
  • Table operation area

Design Tokens

FAQ

  • Why is the table data not updated?
    At present, all parameters of the table component are shallow comparison. That is to say, if the parameter value type is an array or object, you need to manually change its reference to trigger the update. Similarly, if you don't want to trigger additional updates, try not to use literal values when passing parameters directly or define reference parameter values in the render process:
    The above writing method will trigger the update of data in the table every time render (the current selected row will be cleared and the row key array will be expanded, etc.). In order to improve performance and avoid some exceptions, please define some reference type parameters outside the render method as far as possible (if hooks are used, please use useMemo or useState for storage).**
  • Why can't my form line be selected and expanded?
    Please specify a rowKey or set a different "key" attribute for each item of the dataSource. All rows related operations in the table need to be used.
  • How to implement custom sorting or pass parameters to the server for sorting when clicking the sort button?
    The input parameters of the onChange method include pagination, filters, and sorter. Users can customize the sorting of the dataSource according to the sorter.
  • How to add className to a row?
    Use onRow or onHeaderRow.
  • How to style the table cell?
    It can be controlled by column.onHeaderCell and column.onCell.
  • Why cache the previously selected keys for the first parameter of rowSelection onChange?
    This is for the scenario where the selected row keys are lost when data is selected on the first page during paging, and then the data is selected on the second page. If you don't want to use the cached keys, you can filter it from the current dataSource or use the second parameter of rowSelection onChange.
  • Does it support single row selection?
    Table currently does not support single-row selection function, and users can implement single selection in a custom way. Please check the FAQ.
  • How is Table implemented, I want to know more details?
    Please click Semi Table component design
See more Table FAQ and demos, please click Table FAQ