Skip to the content

DataTable

A virtualized table driven by data and columns, with sorting, search, column filters, resizing, selection and pagination built in. Memoize data and columns (React.useMemo), including any Cell or Footer renderer inside columns.
Data Display

Use Table when you compose the rows yourself; use DataTable when you pass data + columns and need sorting, filters, a selection callback or virtualization.

When to use

Use when
  • Hundreds or thousands of rows must scroll smoothly.
  • Users sort, search, filter or resize columns.
  • You need the selected rows back (onRowSelect) or client-side pagination.
  • A row needs more detail than its cells hold: a note, its line items, a small form (renderExpandedContent).
Avoid when
  • A short table whose cells you compose by hand — use Table.
  • Rows of mixed content (forms, cards) — use List.

Usage

Users
Name
Age
Visits
import { DataTable, CellAlign } from '@apollion-dsi/core/data-display/data-table';

const columns = React.useMemo(
  () => [
    { Header: 'Name', accessor: 'name' },
    { Header: 'Visits', accessor: 'visits', align: CellAlign.right, Cell: ({ value }) => `${value} visits` },
  ],
  [],
);

<DataTable title="Users" data={data} columns={columns} hasHeader />;

hasHeader adds the title, the global search and the headerLeftComponent / headerRightComponent slots. Click a header to sort it (disableSortBy opts a column out). The body is at most height tall (default 400px). With no rows, the empty state renders emptyIcon, emptyTitle and emptyDescription.

Columns and rows

  • align takes CellAlign.left | center | right; content starts left.
  • Cell renders any node from { row, value }; Footer renders a column total, shown with hasFooter.
  • setRowColor(row) returns a RowColor (primary, success, alert, error) to tint a whole row.
  • lastRowComponent renders at the last virtual position (a "Load more" button), as one row whose cell spans every column.

Selection and pagination

selectableColumn adds a column of DS Checkboxes (a string titles it); onRowSelect receives every selected row — across pages and filters; selecting a parent in tree mode also reports its sub-rows as their own entries. With onRowSelect, a click on a cell also toggles its row; onRowClick replaces that with your handler. paginated swaps the infinite scroll for pages, after sort and filter. pageSizeOptions={[25]} hides the size selector.

Name
Age
Visits

Mostrando 1-2 de 5

1 / 3

<DataTable data={data} columns={columns} selectableColumn onRowSelect={setSelected} paginated />

Pagination, expansion and column filters are uncontrolled by default (initialPagination, initialExpanded, initialColumnFilters) or controlled with the value + on…Change pair. UI strings default to pt-BR; override them with labels (DataTableLabels).

Tree rows and column filters

getSubRows turns rows into a tree: a chevron column toggles each parent, indented by depth. filterVariant on a column adds a filter popover to its header: 'text' (contains), 'select' (values with counts) or 'range' (min/max). filterFn overrides the match; disableFilters opts a column out.

Name
Status
Age
Visits
const columns = React.useMemo(
  () => [
    { Header: 'Name', accessor: 'name', filterVariant: 'text' },
    { Header: 'Status', accessor: 'status', filterVariant: 'select' },
    { Header: 'Age', accessor: 'age', filterVariant: 'range' },
  ],
  [],
);

<DataTable data={tree} columns={columns} getSubRows={(row) => row.children} initialExpanded />;

Detail panels

renderExpandedContent opens a full-width panel under a row. The chevron column toggles it, and the expanded state is the same one tree mode uses (initialExpanded, or expanded + onExpandedChange). getRowCanExpand limits the toggle to some rows. Panels are measured after they render, so any height works, and the virtualized body stays smooth. expandedContentHeight is only the first estimate.

Expandir
Name
Age
Visits
<DataTable
  data={orders}
  columns={columns}
  getRowCanExpand={(order) => order.lines.length > 0}
  renderExpandedContent={(order) => <OrderLines lines={order.lines} />}
/>

Keep the panel for detail that belongs to one row. Do not use it for a form that edits the whole table, or for content users must compare across rows: put that in a column, or open a Sheet.

Accessibility

  • The scroll viewport is a focusable role="region" named by labels.scrollRegion, then title, then 'Tabela'. Name tables without a title.
  • The grid exposes table roles (role="table" named by title, rows, column headers), so screen readers navigate it as a table. Native div attributes land on the outer wrapper with hasHeader, else on the table viewport.
  • Each sortable header has a sort button (labels.sortColumn) and exposes the order as aria-sort; filter and expand controls are buttons named by labels.filterColumn, labels.expandRow and labels.collapseRow, and expose aria-expanded. The expand column's header carries screen-reader-only text (labels.expandColumn).
  • An open detail panel is a row of its own, with one cell spanning every column, and aria-rowindex / aria-rowcount count it.
  • Selection boxes are Checkboxes named by labels.selectRow and labels.selectAllRows; a string selectableColumn names the select-all box instead. Range and text filter inputs are named by labels.filterRangeMinLabel, labels.filterRangeMaxLabel and labels.filterTextLabel.
  • Default accessible names are pt-BR (Ordenar por <column>, Filtrar <column>, Selecionar linha); pass labels for other languages.

Properties

See also