Table
<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.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
- 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).
- Hundreds of rows, sorting or column filters — use
DataTable. - Label/value pairs, not rows — use
DescriptionList.
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
searchingadds a search input (pt-BR placeholderPesquisar). OnEnter, rows without the term are hidden; when every row is hidden,TableEmptyrenders below. Each search starts from all rows; clearing the box shows them all.rowTypesandshareopen their menus from icon buttons named byrowTypesLabelandshareLabel.TableCheckboxCellas the first cell of each body row andTableHeaderCheckboxCellin the header add selection. Selected rows are highlighted. The selection stays inside theTable— no callback reports it; useDataTableandonRowSelectwhen 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 (withcolumnSum={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
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
titlenames 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
alignTableAlignTableAlignTargetColumns'center'canNextPagebooleannonecanPreviousPagebooleannonecolumnSize[{ width?: stringnumber; type?: "max""min"; }]undefinednonecolumnSumnumbernoneellipsisbooleannoneembeddedbooleanfalsefinalPaginationstringnumbernonehoverablebooleannoneinitialPaginationstringnumbernonelinesPerPage{ label: string; value: any; }[]nonelinesPerPageLabelstring'Linhas por página'linesPerPageValueanynonenextLabelstring'Próximo'onLinesPerPageChange((value: any) => void)noneonNextPage(() => void)noneonPreviousPage(() => void)nonepreviousLabelstring'Anterior'rowSize"Compact""Expansive""Default"'Default'rowTypesbooleannonerowTypesLabelstring'Densidade das linhas'scrollRegionstringtitle ?? 'Tabela'searchingbooleannoneselectednumber[]noneshare{ email?: (() => void); social?: (() => void); }undefinednoneshareLabelstring'Compartilhar'showingText((initial: stringnumber, final: stringnumber, total: stringnumber) => string)nonestackBelow"xs""sm""md""lg""xl"nonestickyHeaderbooleannonestripedbooleannonetitlestringnonetotalPaginationstringnumbernoneParts
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 |