Table

Tables are used to display tabular data using rows and columns. They allow users to quickly scan, sort, compare, and take action on large amounts of data. Table implementation is based on @react-aria/table

import { Table } from '@nextui-org/react';

Anatomy

  • Table: The wrapper that provides props, state, and context to its children.
  • Table.Header: The header of the table and wrapper for the table's header columns.
  • Table.Column: Table columns headers act as a label for all of the cells in that column, and can optionally support user interaction to sort by the column and change the sort order.
  • Table.Body: The body of the table and wrapper for the table's rows. Table body can be configured to display a loading indicator while data is being fetched.
  • Table.Row: Table rows can be navigated to using the arrow keys. Table rows support selection via mouse, touch, or keyboard. Clicking, tapping, or pressing the Space key anywhere in the row selects it.
  • Table.Pagination: Table pagination is used to navigate between pages of data.

Static

A simple example with static rows and columns, cells can also be statically defined as children.

Dynamic

Table generated dynamically using a function based on the data passed to the columns or items prop respectively.

Custom cells

You can render any React component in the cells prop. The row and column props are passed to the component.

Single selection

You can set the selectionMode property as single to limit users to select only a single item at a time.

Multiple selection

You can set the selectionMode property as multiple to allow users to select multiple items at a time.

Colors

Table component allows you to change the color of the selected rows, checkbox, loading and sort icon by passing the color prop.

Bordered

You can change the full style to a bordered Table with the bordered property.

Lined

You can change the full style to a lined Table with the lined and headerLined properties.

Sticked

You can remove the padding of the Table with the sticked property.

Compact

You can reduce the amount of vertical padding that each row contains by using the compact property.

Striped

You can easily add zebra-striping style by using the striped property.

Pagination

You can paginate the Table data by using the Table.Pagination component.

Infinity Pagination

Table supports loading data asynchronously, and will display a progress loading set by the loadingState prop. It also supports infinite scrolling to load more data on demand as the user scrolls, via the onLoadMore prop.

Note: This example performs client side async loading thanks to @react-stately/async-list hook, you can also create a custom implementation of it to fetch the data asynchronously.

Sortable

Table supports sorting its data when a column header is pressed, to set a column as sortable, you can use the allowsSorting property to the column prop.

Note: This example performs client side sorting by passing load and sort functions to the @react-stately/async-list hook and by comparing the data using @react-aria/i18n useCollector hook. See the docs for more information on how to perform server side sorting.

Disabled keys

You can disable specific rows by providing an array of keys to Table through the disabledKeys prop. This will prevent rows from being selectable as shown in the example below.

Note: Its important to have a unique key for each row, otherwise the disabled keys will not work.

Disallow empty selection

Table also supports a disallowEmptySelection prop which forces the user to have at least one row selected all the time. In this mode, if a single row is selected and the user presses it, it will not be deselected.

Note: Its important to have a unique key for each row, otherwise the default selected keys will not work.

No animated

You can disable the animation of the entire Table by using animated={false} property.

APIs

Table Props

AttributeTypeDescriptionDefault
children*TableChildrenThe elements that make up the table. Includes the Header, Body, Columns, and Rows.-
colorSimpleColorsColor of the selected rows, checkbox, loading and sort icon.primary
shadowbooleanDisplay shadow effectfalse
borderedbooleanDisplay a bordered tablefalse
stripedbooleanDisplay zebra-striping stylefalse
fixedbooleanColumn headers remain fixed on scrollfalse
hoverablebooleanHighlight the hovered row, this property is applied automatically in SelectionMode different from nonefalse
stickedbooleanRemove table horizontal and vertical paddingfalse
linedbooleanDisplay a line after each rowfalse
headerLinedbooleanDisplay a line after the header and change its stylesfalse
lineWeightNormalWeightsHeader border weight for headerLined tablenormal
borderWeightNormalWeightsTable border weight for bordered tablenormal
hideLoadingbooleanHide loading component on infinity paginationfalse
animatedbooleanDisplay animated checkboxes, rows and sortable columnstrue
selectionModeSelectionModeThe type of selection that is allowed in the collection.none
selectionBehaviorSelectionBehaviorHow multiple selection should behave in the collection. Go to the @react-aria/table docs for more information.toggle
allowDuplicateSelectionEventsbooleanWhether onSelectionChange should fire even if the new set of keys is the same as the last.-
showSelectionCheckboxesbooleanWhether the row selection checkboxes should be displayed.-
sortDescriptorSortDescriptorThe current sorted column and direction.-
selectedKeysSelectionThe currently selected keys in the collection (controlled).-
defaultSelectedKeysSelectionThe initial selected keys in the collection (uncontrolled).-
disabledKeysSet<Key>A set of keys for rows that are disabled.-
disallowEmptySelectionbooleanWhether the collection allows empty selection.-
onSelectionChange(keys: Selection) => anyHandler that is called when the selection changes.false
onSortChange(descriptor: SortDescriptor) => anyHandler that is called when the sorted column or direction changes.false
ref-forwardRef-
containerCss-Override Table container default CSS style-
css-Override Default CSS style-
as-Changes which tag component outputs-
...TableHTMLAttributesNative props-

Table.Header Props

AttributeTypeDescriptionDefault
children*TableHeaderChildrenA list of Column(s) or a function. If the latter, a list of columns must be provided using the columns prop-
columnsT[]A list of table columns.-

Table.Column Props

AttributeTypeDescriptionDefault
children*TableColumnChildrenStatic child columns or content to render as the column header-
alignTableColumnAlignThe alignment of the column's contents relative to its allotted widthstart
hideHeaderbooleanWhether the column should hide its header textfalse
allowsSortingbooleanWhether the column allows sorting-
isRowHeaderbooleanWhether a column is a row header and should be announced by assistive technology during row navigation-
textValuestringA string representation of the column's contents, used for accessibility announcements-
widthstring numberThe width of the column-
minWidthstring numberThe minimum width of the column-
maxWidthstring numberThe maximum width of the column-
css-Override Default CSS style-

Table.Body Props

AttributeTypeDescriptionDefault
children*CollectionChildren<T>The contents of the table body. Supports static items or a function for dynamic rendering-
itemsIterable<T>A list of row objects in the table body used when dynamically rendering rows-
loadingState() => anyHandler that is called when more items should be loaded, e.g. while scrolling near the bottom-
onLoadMoreIterable<T>A list of row objects in the table body used when dynamically rendering rows-
css-Override Default CSS style-

Table.Row Props

AttributeTypeDescriptionDefault
children*TableRowChildrenRendered contents of the row or row child items-
textValuestringA string representation of the row's contents, used for features like typeahead-
css-Override Default CSS style-

Table.Cell Props

AttributeTypeDescriptionDefault
children*ReactNodeThe contents of the cell-
textValuestringA string representation of the row's contents, used for features like typeahead-
css-Override Default CSS style-

Table Accessibility Props

AttributeTypeDescriptionDefault
idstringThe element's unique identifier. See MDN-
aria-labelstringDefines a string value that labels the current element-
aria-labelledbystringIdentifies the element (or elements) that labels the current element-
aria-describedbystringIdentifies the element (or elements) that describes the object.-
aria-detailsstringIdentifies the element (or elements) that provide a detailed, extended description for the object.-

Table types

Table children

type TableChildren<T> = [
  ReactElement<TableHeaderProps<T>>,
  ReactElement<TableBodyProps<T>>
];

Table header children

type TableHeaderChildren<T> =
  | ColumnElement<T>
  | ColumnElement<T>[]
  | ColumnRenderer<T>;

Table column children

type TableColumnChildren<T> = ReactNode | ColumnElement<T> | ColumnElement<T>[];

Table row children

type TableRowChildren = CellElement | CellElement[] | CellRenderer;

Table column align

type TableColumnAlign = 'start' | 'center' | 'end';

Simple Colors

type SimpleColors = 'primary' | 'secondary' | 'success' | 'warning' | 'error';

Normal Weights

type NormalWeights = 'light' | 'normal' | 'bold' | 'extrabold' | 'black';

Selection mode

type SelectionMode = 'none' | 'single' | 'multiple';

Selection behavior

type SelectionBehavior = 'toggle' | 'replace';

Sort descriptor

type SortDescriptor = {
  column: React.Key;
  direction: 'ascending' | 'descending';
};

Selection

type Selection = 'all' | Set<React.Key>;

Loading state

type LoadingState =
  | 'loading'
  | 'sorting'
  | 'loadingMore'
  | 'error'
  | 'idle'
  | 'filtering';
gradient blue backgroundgradient violet background