@commercetools-uikit/data-table

DataTable

Description

Shows tabular data, defined by a list of items: the rows, and another list with their corresponding definitions: the columns. Both these lists are arrays of objects.

• The rows list defines the items you want to render, where each item only requires a unique id which is used for mapping, and the remaining properties to be shown under each column.
• On the columns list, each object requires a unique key which should correspond to property key of the items of rows that you want to render under this column, and a label which defines the name shown on the header of the column.

These are the only requirements for rendering the most simple table which should suffice for most use cases and is scaled automatically for the available space.

For more advanced configuration and layout customization, a plethora of other options are available, including per-column specific options.

For adding a Row Selection behavior, check the useRowSelection hook which you can use to prepare your rows and columns before passing them to the DataTable component.

Installation

yarn add @commercetools-uikit/data-table

npm --save install @commercetools-uikit/data-table

Additionally install the peer dependencies (if not present)

yarn add react

npm --save install react

Usage

import DataTable from '@commercetools-uikit/data-table';

const rows = [
  { id: 'parasite', title: 'Parasite', country: 'South Korea' },
  { id: 'portrait', title: 'Portrait of a Lady on Fire', country: 'France' },
  { id: 'wat', title: 'Woman at War', country: 'Iceland' },
];

const columns = [
  { key: 'title', label: 'Title' },
  { key: 'country', label: 'Country' },
];

const Example = () => <DataTable rows={rows} columns={columns} />;

export default Example;

Properties

Props	Type	Required	Default	Description
rows	Array: Row[]	✅		The list of data that needs to be rendered in the table. Each object in the list can have any shape as long as it has a unique identifier. The data is rendered by using the callback render function itemRenderer.
columns	Array: TColumn<Row>[] See signature.		[]	The list of columns to be rendered. Each object requires a unique key which should correspond to property key of the items of rows that you want to render under this column, and a label which defines the name shown on the header.
customColumns	Array: TColumn<Row>[] See signature.			The list of columns to be rendered. The columns of the nested items to be rendered in the table. Just like the columns, Each object requires a unique key which should correspond to property key of the items of rows that you want to render under this column, and a label which defines the name shown on the header.
footer	ReactNode			Element to render within the tfoot (footer) element of the table.
maxWidth	union Possible values: number , string			The max width (a number of pixels or a css value string with units) for which the table is allowed to grow. If unset, the table will grow horizontally to fill its parent.
maxHeight	union Possible values: number , string			The max height (a number of pixels or a css value string with units) for which the table is allowed to grow. If unset, the table will grow vertically to fill its parent and we are able to have a sticky header.
onRowClick	Function See signature.			A callback function, called when a user clicks on a row.
isCondensed	boolean		true	Set this to true to reduce the paddings of all cells, allowing the table to display more data in less space.
onColumnResized	Function See signature.			A callback function, called when a column has been resized. Use this callback to get the resized column widths and save them, to be able to restore the value once the user comes back to the page.
disableSelfContainment	boolean		false	Set this to true to take control of the containment of the table and doing it on a parent element. This means that the table will grow in size without adding scrollbars on itself, both vertically and horizontally and, as a consequence, the maxHeight and maxWidth props are ignored. If you need to enforce these constraints, you must also apply them on the parent element. Additionally, the sticky behaviour of the header will get fixed relatively to the closest parent element with position: relative.
disableHeaderStickiness	boolean			Set this to true to prevent the header from being sticky. The header can be sticky only if the table does not have a maxHeight set.
itemRenderer	Function See signature.		(row, column) => row[column.key]	The default function used to render the content of each item in a cell. In case a column has its own renderItem render function, it will take precedence over this function.
wrapHeaderLabels	boolean		true	Set this to false to ensure that every column can render their label in one line. By default the header cell grows in height in case the label does not fit in one line.
verticalCellAlignment	union Possible values: 'top' , 'center' , 'bottom'		'top'	The default cell vertical alignment of each row (not the table header).
horizontalCellAlignment	union Possible values: 'left' , 'center' , 'right'		'left'	The default cell horizontal alignment. In case a column has its own align property, it will take precedence over this value.
sortedBy	string			The key of the column for which the data is currently sorted by.
onSortChange	Function See signature.			A callback function, called when a sortable column's header is clicked. It's required when the isSortable flag is set on at least one column.
sortDirection	union Possible values: 'desc' , 'asc'			The sorting direction.
renderNestedRow	Function See signature.			Custom row renderer for nested rows.
maxExpandableHeight	number			If this is provided, then it should control the height of the expanded rows. In the event where there is more content than the maxHeight, a scrollbar should make provision for the overflow.

Signatures

Signature columns

{
  /**
   * The unique key of the column that is used to identify your data type.
   * You can use this value to determine which value from a row item should be rendered.
   * <br>
   * For example, if the data is a list of users, where each user has a `firstName` property,
   * the column key should be `firstName`, which renders the correct value by default.
   * The key can also be some custom or computed value, in which case you need to provide
   * an explicit mapping of the value by implementing either the `itemRendered` function or
   * the column-specific `renderItem` function.
   */
  key: string;
  /**
   * The label of the column that will be shown on the column header.
   */
  label: ReactNode;
  /**
   * Sets a width for this column. Accepts the same values as the ones specified for
   * individual [grid-template-columns](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns).
   * <br>
   * For example, using `minmax` pairs (e.g. `minmax(200px, 400px)`), a combinations of
   * fraction values (`1fr`/`2fr`/etc), or fixed values such as `200px`.
   * By default, the column grows according to the content and respecting the total table available width.
   */
  width?: string;
  /**
   * Use this to override the table's own `horizontalCellAlignment` prop for this specific column.
   */
  align?: 'left' | 'center' | 'right';
  /**
   * A callback function, called when the header cell is clicked.
   */
  onClick?: (event: MouseEventHandler) => void;
  /**
   * A callback function to render the content of cells under this column, overriding
   * the default `itemRenderer` prop of the table.
   */
  renderItem?: (row: Row, isRowCollapsed: boolean) => ReactNode;
  /**
   * Use this prop to place an `Icon` or `IconButton` on the left of the column label.
   * It is advised to place these types of components through this prop instead of `label`,
   * in order to properly position and align the elements.
   * This is particularly useful for medium-sized icons which require more vertical space than the typography.
   */
  headerIcon?: ReactNode;
  /**
   * Set this to `true` to allow text content of this cell to be truncated with an ellipsis,
   * instead of breaking into multiple lines.
   * <br>
   * NOTE: when using this option, it is recommended to specify a `width` for the column, because
   * if the table doesn't have enough space for all columns, it will start clipping the columns
   * with _truncated_ content, and if no `width` is set (or the value is set `auto` -- the default)
   * it can shrink until the column disappears completely.
   * By enforcing a minimum width for these columns, the table will respect them and grow horizontally,
   * adding scrollbars if needed.
   */
  isTruncated?: boolean;
  /**
   * Set this to `true` to show a sorting button, which calls `onSortChange` upon being clicked.
   * You should enable this flag for every column you want to be able to sort.
   * When at least one column is sortable, the table props `sortBy`, `sortDirection` and `onSortChange` should be provided.
   */
  isSortable?: boolean;
  /**
   * Set this to `true` to prevent this column from being manually resized by dragging
   * the edge of the header with a mouse.
   */
  disableResizing?: boolean;
  /**
   * Set this to `true` to prevent click event propagation for this cell.
   * You might want this if you need the column to have its own call-to-action or input while
   * the row also has a defined `onRowClick`.
   */
  shouldIgnoreRowClick?: boolean;
}

Signature customColumns

{
  /**
   * The unique key of the column that is used to identify your data type.
   * You can use this value to determine which value from a row item should be rendered.
   * <br>
   * For example, if the data is a list of users, where each user has a `firstName` property,
   * the column key should be `firstName`, which renders the correct value by default.
   * The key can also be some custom or computed value, in which case you need to provide
   * an explicit mapping of the value by implementing either the `itemRendered` function or
   * the column-specific `renderItem` function.
   */
  key: string;
  /**
   * The label of the column that will be shown on the column header.
   */
  label: ReactNode;
  /**
   * Sets a width for this column. Accepts the same values as the ones specified for
   * individual [grid-template-columns](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns).
   * <br>
   * For example, using `minmax` pairs (e.g. `minmax(200px, 400px)`), a combinations of
   * fraction values (`1fr`/`2fr`/etc), or fixed values such as `200px`.
   * By default, the column grows according to the content and respecting the total table available width.
   */
  width?: string;
  /**
   * Use this to override the table's own `horizontalCellAlignment` prop for this specific column.
   */
  align?: 'left' | 'center' | 'right';
  /**
   * A callback function, called when the header cell is clicked.
   */
  onClick?: (event: MouseEventHandler) => void;
  /**
   * A callback function to render the content of cells under this column, overriding
   * the default `itemRenderer` prop of the table.
   */
  renderItem?: (row: Row, isRowCollapsed: boolean) => ReactNode;
  /**
   * Use this prop to place an `Icon` or `IconButton` on the left of the column label.
   * It is advised to place these types of components through this prop instead of `label`,
   * in order to properly position and align the elements.
   * This is particularly useful for medium-sized icons which require more vertical space than the typography.
   */
  headerIcon?: ReactNode;
  /**
   * Set this to `true` to allow text content of this cell to be truncated with an ellipsis,
   * instead of breaking into multiple lines.
   * <br>
   * NOTE: when using this option, it is recommended to specify a `width` for the column, because
   * if the table doesn't have enough space for all columns, it will start clipping the columns
   * with _truncated_ content, and if no `width` is set (or the value is set `auto` -- the default)
   * it can shrink until the column disappears completely.
   * By enforcing a minimum width for these columns, the table will respect them and grow horizontally,
   * adding scrollbars if needed.
   */
  isTruncated?: boolean;
  /**
   * Set this to `true` to show a sorting button, which calls `onSortChange` upon being clicked.
   * You should enable this flag for every column you want to be able to sort.
   * When at least one column is sortable, the table props `sortBy`, `sortDirection` and `onSortChange` should be provided.
   */
  isSortable?: boolean;
  /**
   * Set this to `true` to prevent this column from being manually resized by dragging
   * the edge of the header with a mouse.
   */
  disableResizing?: boolean;
  /**
   * Set this to `true` to prevent click event propagation for this cell.
   * You might want this if you need the column to have its own call-to-action or input while
   * the row also has a defined `onRowClick`.
   */
  shouldIgnoreRowClick?: boolean;
}

Signature onRowClick

(row: Row, rowIndex: number, columnKey: string) => void

Signature onColumnResized

(args: TColumn<Row>[]) => void

Signature itemRenderer

(item: Row, column: TColumn<Row>, isRowCollapsed: boolean) => ReactNode;

Signature onSortChange

(columnKey: string, sortDirection: 'asc' | 'desc') => void

Signature renderNestedRow

(row: Row) => ReactNode;