@gravity-ui/react-data-table

v2.1.1

Published

8 months ago

DataTable component

Downloads

4,754

0High
0Medium
0Low

React Data Table ·

A React component for rendering tables.

Cell grouping is supported: rows are first sorted by grouped columns. Grouping is incompatible with the dynamicRender option.

Multi-column sorting is also supported. Ctrl+Click on a column adds a column at the end of the sort list. A simple Click sorts the table by this column only. Sorting order is switched in the sequence: none -> default -> reversed default -> none.

Properties

| Property | Type | Required | Default | :---------------- | :--------- | :------: | columns | Array | ✓ | headerData | Array | | data | Array | ✓ | footerData | Array | | startIndex | Number | | settings | Object | | emptyDataMessage | String | | renderEmptyRow | Function | | rowClassName | Function | | rowKey | Function | | initialSortOrder | Object | | theme | String | | onSort | Function | | sortOrder | Object | | onResize | Function | | visibleRowIndex | Function | | onRowClick | Function | | nullBeforeNumbers | Boolean | | getColSpansOfRow | Function | | Description | | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | List of table columns | | | A list of rows with data that will be shown inside the header. If the header is sticky, the rows will also stick. The same methods apply to them as to rows in data (headerData) | | | List of data rows | | | A list of rows with data to be sent into the table footer. The same methods apply to them as to strings in data | | 0 | Initial index (used to show row indexes) | | | Table settings | | 'No data' | The message shown when the data is empty | | | A custom renderer for an empty table row, accepts an array of columns (columns) => ReactNode | | | A method that sets the class for a string (row, index, isFooterRow, isHeaderRow) => (<string> ) | | | A method that returns the value of react-key (row, index) => (<scalar_type_value> ). The default method returns row.id || index | | | Initial sorting in the format{columnId: <string>, order: <DataTable.ASCENDING | DataTable.DESCENDING>} or a list of such objects. | | 'yandex-cloud' | The name of the theme. To use the built-in table theme, use the 'legacy' value. For compatibility with @gravity-ui/uikit colors, use 'yandex-cloud' (default) | | | Sort listener ([{columnId: <string>, order: <DataTable.ASCENDING | DataTable.DESCENDING>}]) => void. Use it to save the sorting state and pass it to the initialSortOrder on page refresh. | | | Sorting in the format {columnId: <string>, order: <DataTable.ASCENDING | DataTable.DESCENDING>} or a list of such objects. | | | Resize listener (columnId: string, newWidth: number) => void. Use it to save new column width. | | | A method (row, index) => number that returns the row index shown in the column enabled by the displayIndices flag. Use it to specify a correct row index when applying external sorting | | | Click listener for a row (row, index, event) => void | | | A flag that sets the position of null/undefined values when sorting. If true, null/undefined values are shown at the top in the case of ascending order and at the bottom in the case of descending order. If false/undefined, they are shown at the bottom | | | Configuring column spanning for each row ({ row, columns, index, headerData, span, footer, odd }) => {[colName: string]: number} / undefined |

Settings

externalSort

Disables data sorting on the component side. Please note that:

The table continues to be the primary source of the sort state (selected columns and sort direction) and is also responsible for the correct rendering of table headers in accordance with this state.
The external environment must pass to the table correctly sorted rows in props.data responding to the props.onSort callback call.
Grouping of column values is disabled (see Column.group).

Column

Columns let you flexibly customize rendering of cells. In its simplest form, the column description looks as follows:

{
  "name": "column_name"
}

The cell will show row.column_name as it is.

The name field is the only mandatory field. The remaining fields are described below:

| Property | Type | Description | | :------------- | :------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Column name and default value for the header and accessor | | header | string or node | Column header | | headerTitle | string | Header title | | className | string | Column class | | width | string \| number | Column width | | resizeable | boolean | Determines whether column width can be changed. Applied only if onResize function is passed. | | resizeMinWidth | number | Min column width for resize. | | resizeMaxWidth | number | Max column width for resize. | | align | DataTable.LEFT DataTable.CENTER DataTable.RIGHT | Text alignment in a cell | | accessor | func | Callback (row) => (value). Use it if you want to display deeply "hidden" values in the column. For example: (row) => (row.child1.child2[0].value) | | title | string or func:string | Callback (row) => (title). Lets you set a fixed title (in the case of string) or a dynamic title for column cells. Returns a string. | | render | func:node | Callback ({value, row, index}) => (node). Lets you render a cell in an arbitrary way. As an input, it gets a value, a whole row, or a row index. Returns a React node. | | customStyle | func | Callback ({row, index, header, name}) => (styleObject). Lets you set a custom style for the cell. In the callback, you pass a string with data, an index, a column name, and a flag whether the cell is a header. At the output, you expect an object with styles following the React syntax. | | onClick | func | Callback (row, column) => (). The onClick listener on the cell. | | sortable | Boolean | Whether the column is sortable. | | defaultOrder | DataTable.ASCENDING DataTable.DESCENDING | A default sorting order in the column. | | sortAccessor | func | Callback (row) => (value). Use it if you want to sort by a value other than value, or if value is non-scalar. | | sortAscending | func | Callback ({row, index, span?}, {row, index, span?}) => (sortValue). Use if you want to customize sorting completely. | | sub | array | Nested columns | | group | Boolean | Groups the same values into one cell, allowing you to create complex tables. More details | | autogroup | Boolean | Enables ascending sorting across all columns with group, resulting in autogrouping. Defaults to true |

group

Groups the same values into one cell. Please note that:

Grouping is incompatible with the Settings.dynamicRender option, and, when they are enabled together, the table might work poorly.
Grouping is disabled when the Settings.externalSort option is enabled
It is worth disabling the Settings.stripedRows and Settings.highlightRows settings.

Multi-level header

Nested columns are set up in the sub field. For columns with attachments, except for the sub field, only fields that affect the header make sense: name, header, headerTitle, align, and customStyle.

headerData

The headerData property lets you add rows to the beginning of the table. However, if the header is sticky, the rows will stick along with the header. In the sticky header mode, such rows won't affect the column width, so you might need to specify the column width.

Customizing with themes

The table contains several customized elements. To set colors for them, use CSS variables (in the example, the topic values are internal):

--data-table-color-base: #ffffff;
--data-table-color-stripe: rgba(0, 0, 0, 0.03);
--data-table-border-color: #dddddd;
--data-table-color-hover-area: #ffeba0;
--data-table-color-footer-area: var(--data-table-color-base);

Custom cell colors

Table cells can be rendered using an arbitrary style. If used incorrectly, it might break the layout!

Using react-data-table with non-standard fonts

When using the stickyHead prop and a non-standard font for table data, sizes of header columns and table columns might mismatch. This might be the issue if the table data has been loaded and the table rendered before the browser has loaded a specific font.

To avoid this problem, load the desired font before rendering the table. You can do this in one of the following ways:

Use <link rel="preload"> in the <head> element of your HTML code

<head>
  <meta charset="utf-8" />
  <title>Web font example</title>

  <link
    rel="preload"
    href="fonts/my-font.woff2"
    as="font"
    type="font/woff2"
    crossorigin="crossorigin"
  />
  <link
    rel="preload"
    href="fonts/my-font.woff"
    as="font"
    type="font/woff"
    crossorigin="crossorigin"
  />
  <link
    rel="preload"
    href="fonts/my-font.ttf"
    as="font"
    type="font/ttf"
    crossorigin="crossorigin"
  />

  <link href="style.css" rel="stylesheet" type="text/css" />
</head>
<body>
  ...
</body>

Please note that in this case, the font is loaded before all the content on the page is received and loaded. If you use this font only to render tables in your service, and tables aren't core to your service, the user will have to wait for a font they might never need again to upload. This method is also not supported by some modern browsers. Read more about this here.

Use the fontfaceobserver package

To load a font from the JS code, first define it by the @font-face directive in the CSS code:

@font-face {
  font-family: 'My font';
  src: url('fonts/my-font.woff2') format('woff2'),
       url('fonts/my-font.woff') format('woff');
       url('fonts/my-font.ttf') format('ttf');
  font-weight: 400;
  font-style: normal;
}

Then you can preload the font directly with loading data for the table itself.

For one font face:

import FontFaceObserver from 'fontfaceobserver';

function preloadTableFont() {
    return new FontFaceObserver('My font').load();
}

function fetchData() {
    ...
}

function getTableData() {
  return Promise.all([
    fetchData(),
    preloadTableFont(),
  ])
  .then([data] => {
    ...
  })
  .catch((err) => {
    ...
  })
}

For multiple font faces:

import FontFaceObserver from 'fontfaceobserver';

const lightFont = new FontFaceObserver('My font', {weight: 300});
const regularFont = new FontFaceObserver('My font', {weight: 400});

function preloadTableFont() {
    return Promise.all([
        lightFont.load(),
        regularFont.load(),
    ]);
}

function fetchData() {
    ...
}

function getTableData() {
  return Promise.all([
    fetchData(),
    preloadTableFont(),
  ])
  .then([data] => {
    ...
  })
  .catch((err) => {
    ...
  })
}

This method is fully supported by browsers and lets you download the font only for users who have opened the table.

Usage

const data = [];
const columns = [];
const startIndex = 0;

return <DataTable data={data} columns={columns} startIndex={startIndex} />;

For more information, see the sample code.