Skip to the content

Table

A semantic HTML <table> that you compose from parts: TableHeader, TableBody, TableRow, TableCell. Every row is in the DOM — there is no virtualization — so keep it to small and medium tables.
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
  • A few dozen rows where <table> semantics help screen readers and copy-paste.
  • Each cell composes its own content: links, avatars, badges, buttons.
  • A catalog table that must stack into blocks on a phone (stackBelow).
Avoid when

Usage

Pokedex
No.
Name
001
Bulbasaur
<Table title="Pokedex">
  <TableHeader>
    <TableRow>
      <TableHeaderCell>No.</TableHeaderCell>
      <TableHeaderCell>Name</TableHeaderCell>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>001</TableCell>
      <TableCell>Bulbasaur</TableCell>
    </TableRow>
  </TableBody>
</Table>

Every part imports from @apollion-dsi/core/data-display/table, also under a short alias (Thead, Tr, Td…). Put TableHeader first and TableBody second: search, selection and totals read the rows of the second child.

Layout

Sticky header, scroll region and frame

stickyHeader pins the <thead>; bound the height of a parent (<Paper maxHeight="500px">) so the table scrolls. While it scrolls (stickyHeader or columnSize, with more than one row), the viewport is a focusable role="region", so a keyboard user can scroll it. Name it with scrollRegion; it falls back to title, then 'Tabela'. Inside a Paper or Card, set embedded: no top border on the header, no bottom border on the last row.

Stacked rows

stackBelow takes a container size (xs … xl). Below it, each row becomes a block: the first cell is the title, the others read header · value. The width that counts is the table's own slot, not the viewport. Use it for 3–6 column catalogs; keep the table layout for numeric columns read top to bottom.

Labels come from the TableHeader text by column. Pass label on a TableCell when the header is not plain text; label="" renders the value alone, trailing. A hiddenLabel header (an actions column) does the same.

Alignment

align on the Table sets every column ('left' | 'center' | 'right', default centre) or one column per entry ([{ direction: 'right', target: '3' }]). align on a TableCell or TableHeaderCell (start · center · end) wins for that cell; set it on a header and its cells to align a column. Both are ignored while stacked.

Search, selection and totals

  • searching adds a search input (pt-BR placeholder Pesquisar). On Enter, rows without the term are hidden; when every row is hidden, TableEmpty renders below. Each search starts from all rows; clearing the box shows them all.
  • rowTypes and share open their menus from icon buttons named by rowTypesLabel and shareLabel.
  • TableCheckboxCell as the first cell of each body row and TableHeaderCheckboxCell in the header add selection. Selected rows are highlighted. The selection stays inside the Table — no callback reports it; use DataTable and onRowSelect when you need it.
  • columnSum (0-based column index) sums that column's integer cell text. An empty <TableFooter /> as the last child shows "Total:" and the sum (with columnSum={0} the label is omitted).

Pagination

The pagination bar renders above the table when initialPagination, finalPagination, totalPagination and linesPerPage are all set — pass the range as non-zero, 1-based values (0 hides the bar). It is stateless: you own the page index and the row slice. onPreviousPage / onNextPage add the navigation; linesPerPageValue + onLinesPerPageChange control the rows-per-page selector.

Navigable pagination
Showing 1 - 3 of 10 items
Rows per page
3
No.
Name
Type
001
Bulbasaur
Grass
004
Charmander
Fire
007
Squirtle
Water
<Table initialPagination={from} finalPagination={to} totalPagination={total} linesPerPage={sizes} onNextPage={next}>
  {/* TableHeader, and a TableBody with the current slice */}
</Table>

The buttons enable from the numeric range; pass canPreviousPage / canNextPage for formatted counts ("1.234"). Strings default to pt-BR: override showingText, linesPerPageLabel, previousLabel and nextLabel.

Accessibility

  • A visible title names the table (aria-labelledby).
  • Give an actions column a text header with hiddenLabel; never leave a <th> empty.
  • Stacked rows keep the <table> and restate its ARIA roles; the visible label prefix is decorative.

Properties

Parts

Part
Renders
Alias
Own props
TableHeader
<thead>
Thead
—
TableBody
<tbody>
Tbody
—
TableRow
<tr>
Tr
—
TableHeaderCell
<th>
Th
align, hiddenLabel, bgColor
TableCell
<td>
Td
align, label, colSpan, bgColor, ellipsis
TableHeaderCheckboxCell
<th> + select-all box
Thc
children (checkbox label)
TableCheckboxCell
<td> + row checkbox
Tdc
children (checkbox label)
TableFooter
<tfoot>
Tfooter
children (ignored with columnSum)
TableEmpty
empty-state block
—
titleEmpty, subtitleEmpty, iconPropsEmpty
TablePagination
range, selector, nav bar
—
set through the Table pagination props
Scrolls sideways inside the table. The page does not.

See also