Table
Composable responsive data table with typed templates, controlled selection and pagination, sticky regions, and explicit loading, error, and empty states.
- Selector
- ui-table
- Package
- @ngnova/ui/table
Import
import { UiTableComponent, UiTableCellDirective, UiTableHeaderDirective } from '@ngnova/ui/table';Usage & variants
Live examples use the public ui-table API, paired with the exact snippet a product team would paste into an Angular app.
Basic table
Describe columns and rows with typed data, and provide a caption for screen-reader context.
| Category | Status | Owner | |
|---|---|---|---|
| Button | Foundation | Ready | Design system |
| Input | Forms | Ready | Forms |
| Modal | Overlay | A11y review | Platform |
Controlled sorting
Own the sort state in the parent so local arrays, server requests, or cached queries can respond consistently.
| Button | Foundation | Ready | Design system |
| Input | Forms | Ready | Forms |
| Modal | Overlay | A11y review | Platform |
Multiple row selection
Use stable row keys for controlled checkbox selection, including the select-all control.
| Category | Status | Owner | ||
|---|---|---|---|---|
| Button | Foundation | Ready | Design system | |
| Input | Forms | Ready | Forms | |
| Modal | Overlay | A11y review | Platform |
0 components selected
Custom headers and cells
Project templates by column key to add contextual headers and rich cell presentation.
| Category | Status signal | Owner | |
|---|---|---|---|
| Button | Foundation | Ready | Design system |
| Input | Forms | Ready | Forms |
| Modal | Overlay | A11y review | Platform |
Pagination and sticky columns
Coordinate server-style pages while keeping the selection and first data columns visible during scrolling.
| Category | Status | Owner | ||
|---|---|---|---|---|
| Button | Foundation | Ready | Design system | |
| Input | Forms | Ready | Forms | |
| Modal | Overlay | A11y review | Platform |
Loading, empty, and error states
Communicate asynchronous table states with built-in status and alert semantics.
| Component |
|---|
| Loading releases... |
| Component |
|---|
| No matching components. |
| Component |
|---|
| Release data is unavailable. |
Production guidance
Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.
When to use
Use for structured datasets where users compare rows and columns.
Watch for
Loading and empty states span at least one column and mark the table busy only while loading.
Product recipes
Apply Table in distinct, copyable product scenarios—not just an isolated component state.
Controlled selection and pagination
Selection, sorting, and page requests are immutable controlled events; parent code owns data and server requests.
1 2 3 4 5 6 7 8 9 10 11 12 13 14
<ui-table
[columns]="columns"
[rows]="components"
rowKey="id"
selectionMode="multiple"
[selectedKeys]="selectedKeys()"
(selectedKeysChange)="selectedKeys.set($event)"
[page]="page()"
[pageSize]="25"
[totalItems]="totalItems()"
(pageChange)="loadPage($event)"
(rowSelected)="openComponent($event)"
(sortChange)="sortComponents($event)"
/>Composed cells and headless state
Optional templates own rich rendering while a separate state controller coordinates data requests without inflating the basic table entry point.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
import { createUiTableState } from '@ngnova/ui/table-state';
readonly tableState = createUiTableState({ pageSize: 25 });
<ui-table
[columns]="columns"
[rows]="rows"
[sort]="tableState.sort()"
(sortChange)="tableState.setSort($event)"
>
<ng-template uiTableHeader="status" let-column>
{{ column.header }} signal
</ng-template>
<ng-template uiTableCell="status" let-value let-row="row" let-rowIndex="rowIndex">
<app-status [value]="value" [record]="row" [position]="rowIndex" />
</ng-template>
</ui-table>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
columns [] readonly UiTableColumn[] Column definitions with key, header, alignment ('start' by default; 'start' | 'center' | 'end' | 'left' | 'right'), sorting, and optional start/end sticky placement.
rows [] readonly UiTableRow[] Records rendered in the table body.
emptyText 'No records found.' string Message shown when no rows are available.
loadingText 'Loading records...' string Message shown while loading.
errorText 'Unable to load records.' string Message announced when the explicit error state is active.
caption '' string Accessible table name rendered as a caption.
captionVisible false boolean Shows the caption visually instead of using screen-reader-only text.
rowKey '' string Row property used as stable rendering identity; index is the fallback.
sort null UiTableSort | null Optional controlled sort state; otherwise sort indication is managed internally.
loading false boolean Shows the loading state.
error false boolean Shows the error state after loading; loading takes precedence and empty is the fallback.
selectable false boolean Makes rows focusable and emits rowSelected on click, Enter, or Space.
selectionMode 'none' 'none' | 'single' | 'multiple' Enables semantic radio or checkbox selection. A stable rowKey is required for selectable rows.
selectedKeys null readonly UiTableRowKey[] | null Optional controlled selected keys. Null enables internal visual state while still emitting immutable changes.
selectionColumnLabel 'Row selection' string Screen-reader label for the single-selection column header.
selectAllAriaLabel 'Select all rows on this page' string Localized accessible label for the visible-row bulk selection control.
rowSelectionAriaLabel 'Select row' string Localized accessible-label prefix for row selection controls.
stickyHeader false boolean Constrains the table viewport and keeps the header visible while scrolling.
stickySelectionColumn false boolean Keeps the selection column visible during horizontal scrolling.
page 1 number Controlled one-based current page.
pageSize 0 number Items per page; values above zero enable the compact pagination footer.
totalItems 0 number Total result count used for page boundaries and the visible range summary.
paginationAriaLabel 'Table pagination' string Accessible name for the pagination navigation landmark.
previousPageLabel 'Previous' string Visible localized label for the previous-page action.
nextPageLabel 'Next' string Visible localized label for the next-page action.
previousPageAriaLabel 'Previous page' string Localized accessible label for the previous-page action.
nextPageAriaLabel 'Next page' string Localized accessible label for the next-page action.
uiTableCell optional directive Associates an ng-template with a column key and exposes value, row, column, and rowIndex context.
uiTableHeader optional directive Associates an ng-template with a column key and exposes the column definition context.
| Name | Type | Default | Description |
|---|---|---|---|
columns | readonly UiTableColumn[] | [] | Column definitions with key, header, alignment ('start' by default; 'start' | 'center' | 'end' | 'left' | 'right'), sorting, and optional start/end sticky placement. |
rows | readonly UiTableRow[] | [] | Records rendered in the table body. |
emptyText | string | 'No records found.' | Message shown when no rows are available. |
loadingText | string | 'Loading records...' | Message shown while loading. |
errorText | string | 'Unable to load records.' | Message announced when the explicit error state is active. |
caption | string | '' | Accessible table name rendered as a caption. |
captionVisible | boolean | false | Shows the caption visually instead of using screen-reader-only text. |
rowKey | string | '' | Row property used as stable rendering identity; index is the fallback. |
sort | UiTableSort | null | null | Optional controlled sort state; otherwise sort indication is managed internally. |
loading | boolean | false | Shows the loading state. |
error | boolean | false | Shows the error state after loading; loading takes precedence and empty is the fallback. |
selectable | boolean | false | Makes rows focusable and emits rowSelected on click, Enter, or Space. |
selectionMode | 'none' | 'single' | 'multiple' | 'none' | Enables semantic radio or checkbox selection. A stable rowKey is required for selectable rows. |
selectedKeys | readonly UiTableRowKey[] | null | null | Optional controlled selected keys. Null enables internal visual state while still emitting immutable changes. |
selectionColumnLabel | string | 'Row selection' | Screen-reader label for the single-selection column header. |
selectAllAriaLabel | string | 'Select all rows on this page' | Localized accessible label for the visible-row bulk selection control. |
rowSelectionAriaLabel | string | 'Select row' | Localized accessible-label prefix for row selection controls. |
stickyHeader | boolean | false | Constrains the table viewport and keeps the header visible while scrolling. |
stickySelectionColumn | boolean | false | Keeps the selection column visible during horizontal scrolling. |
page | number | 1 | Controlled one-based current page. |
pageSize | number | 0 | Items per page; values above zero enable the compact pagination footer. |
totalItems | number | 0 | Total result count used for page boundaries and the visible range summary. |
paginationAriaLabel | string | 'Table pagination' | Accessible name for the pagination navigation landmark. |
previousPageLabel | string | 'Previous' | Visible localized label for the previous-page action. |
nextPageLabel | string | 'Next' | Visible localized label for the next-page action. |
previousPageAriaLabel | string | 'Previous page' | Localized accessible label for the previous-page action. |
nextPageAriaLabel | string | 'Next page' | Localized accessible label for the next-page action. |
uiTableCell | directive | optional | Associates an ng-template with a column key and exposes value, row, column, and rowIndex context. |
uiTableHeader | directive | optional | Associates an ng-template with a column key and exposes the column definition context. |
Outputs
rowSelected OutputEmitterRef<UiTableRow> Emits the clicked row when selectable.
sortChange OutputEmitterRef<UiTableSort> Emits the requested sort key and direction.
selectedKeysChange OutputEmitterRef<readonly UiTableRowKey[]> Emits a frozen next selection after row or visible-page bulk interaction.
pageChange OutputEmitterRef<number> Emits a bounded one-based page request; the consumer remains state owner.
| Name | Type | Description |
|---|---|---|
rowSelected | OutputEmitterRef<UiTableRow> | Emits the clicked row when selectable. |
sortChange | OutputEmitterRef<UiTableSort> | Emits the requested sort key and direction. |
selectedKeysChange | OutputEmitterRef<readonly UiTableRowKey[]> | Emits a frozen next selection after row or visible-page bulk interaction. |
pageChange | OutputEmitterRef<number> | Emits a bounded one-based page request; the consumer remains state owner. |
Accessibility
- Uses semantic table, thead, tbody, th, and td elements.
- Sortable headers use native buttons.
- Provide caption for the table accessible name; loading and empty messages use status semantics while failures use role alert.
- Single and multiple selection use native radio and checkbox controls with localized names and aria-selected row state.
- Pagination is exposed as a named navigation landmark with a live visible-range summary.
Keyboard behavior
- Sortable header buttons are reachable by Tab and activated with Enter or Space.
- Selectable rows enter the Tab order and emit selection from Enter or Space as well as pointer clicks.
- Selection controls and pagination actions retain native checkbox, radio, and button keyboard behavior.
Testing guidance
- Assert captions, rows, loading/error/empty precedence, controlled and internal selection, bulk selection, bounded pagination, sticky classes, sorting, composed contexts, stable keys, headless snapshots, and harness interaction.