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.

Attribute	Type	Description	Default
children*	TableChildren	The elements that make up the table. Includes the `Header`, `Body`, `Columns`, and `Rows`.	-
color	SimpleColors	Color of the selected rows, checkbox, loading and sort icon.	`primary`
shadow	`boolean`	Display shadow effect	`false`
bordered	`boolean`	Display a bordered table	`false`
striped	`boolean`	Display zebra-striping style	`false`
fixed	`boolean`	Column headers remain fixed on scroll	`false`
hoverable	`boolean`	Highlight the hovered row, this property is applied automatically in SelectionMode different from `none`	`false`
sticked	`boolean`	Remove table horizontal and vertical padding	`false`
lined	`boolean`	Display a line after each row	`false`
headerLined	`boolean`	Display a line after the header and change its styles	`false`
lineWeight	NormalWeights	Header border weight for `headerLined` table	`normal`
borderWeight	NormalWeights	Table border weight for `bordered` table	`normal`
hideLoading	`boolean`	Hide loading component on infinity pagination	`false`
animated	`boolean`	Display animated checkboxes, rows and sortable columns	`true`
selectionMode	SelectionMode	The type of selection that is allowed in the collection.	`none`
selectionBehavior	SelectionBehavior	How multiple selection should behave in the collection. Go to the @react-aria/table docs for more information.	`toggle`
allowDuplicateSelectionEvents	`boolean`	Whether `onSelectionChange` should fire even if the new set of keys is the same as the last.	-
showSelectionCheckboxes	`boolean`	Whether the row selection checkboxes should be displayed.	-
sortDescriptor	SortDescriptor	The current sorted column and direction.	-
selectedKeys	Selection	The currently selected keys in the collection (controlled).	-
defaultSelectedKeys	Selection	The initial selected keys in the collection (uncontrolled).	-
disabledKeys	`Set<Key>`	A set of keys for rows that are disabled.	-
disallowEmptySelection	`boolean`	Whether the collection allows empty selection.	-
onCellAction	`(key: Key) => void`	Handler that is called when a user performs an action on the cell.	-
onRowAction	`(key: Key) => void`	Handler that is called when a user performs an action on the row.	-
onSelectionChange	`(keys: Selection) => any`	Handler that is called when the selection changes.	`false`
onSortChange	`(descriptor: SortDescriptor) => any`	Handler 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	-
...	`TableHTMLAttributes`	Native props	-

Table.Header Props

Attribute	Type	Description	Default
children*	TableHeaderChildren	A list of Column(s) or a function. If the latter, a list of columns must be provided using the columns prop	-
columns	`T[]`	A list of table columns.	-

Table.Column Props

Attribute	Type	Description	Default
children*	TableColumnChildren	Static child columns or content to render as the column header	-
align	TableColumnAlign	The alignment of the column's contents relative to its allotted width	`start`
hideHeader	`boolean`	Whether the column should hide its header text	`false`
allowsSorting	`boolean`	Whether the column allows sorting	-
isRowHeader	`boolean`	Whether a column is a row header and should be announced by assistive technology during row navigation	-
textValue	`string`	A string representation of the column's contents, used for accessibility announcements	-
width	`string` `number`	The width of the column	-
minWidth	`string` `number`	The minimum width of the column	-
maxWidth	`string` `number`	The maximum width of the column	-
css	-	Override Default CSS style	-

Table.Body Props

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

Table.Row Props

Attribute	Type	Description	Default
children*	TableRowChildren	Rendered contents of the row or row child items	-
textValue	`string`	A string representation of the row's contents, used for features like typeahead	-
css	-	Override Default CSS style	-

Table.Cell Props

Attribute	Type	Description	Default
children*	`ReactNode`	The contents of the cell	-
textValue	`string`	A string representation of the row's contents, used for features like typeahead	-
css	-	Override Default CSS style	-

Table Accessibility Props

Attribute	Type	Description	Default
id	`string`	The element's unique identifier. See MDN	-
aria-label	`string`	Defines a string value that labels the current element	-
aria-labelledby	`string`	Identifies the element (or elements) that labels the current element	-
aria-describedby	`string`	Identifies the element (or elements) that describes the object.	-
aria-details	`string`	Identifies 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';

Pagination Collapse

Created by Junior Garcia

Deployed on

Documentation