Table Virtual Scroll
Optional Angular CDK-powered fixed-size row virtualization for large datasets with typed templates and bounded DOM rendering.
- Selector
- ui-table-virtual-scroll
- Package
- @ngnova/ui/table-virtual-scroll
Import
import { UiTableVirtualScrollComponent, UiTableVirtualRowDirective } from '@ngnova/ui/table-virtual-scroll';Usage & variants
Live examples use the public ui-table-virtual-scroll API, paired with the exact snippet a product team would paste into an Angular app.
Large release dataset
Optional Angular CDK-powered fixed-size row virtualization for large datasets with typed templates and bounded DOM rendering.
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 thousands of uniform-height rows when paging alone does not match the interaction.
Watch for
All rows must have the configured fixed itemSize; variable-height rows require a different strategy.
Product recipes
Apply Table Virtual Scroll in distinct, copyable product scenarios—not just an isolated component state.
Ten-thousand-row viewport
Only the visible range and buffers are mounted; the row template receives its absolute dataset index.
1 2 3 4 5 6 7 8 9 10 11 12
<ui-table-virtual-scroll
[rows]="records"
[itemSize]="52"
[minBufferPx]="208"
[maxBufferPx]="416"
height="28rem"
ariaLabel="Audit records"
>
<ng-template uiTableVirtualRow let-row let-index="index">
<app-audit-row [record]="row" [position]="index + 1" />
</ng-template>
</ui-table-virtual-scroll>Stable identity and imperative navigation
Provide stable identity for immutable refreshes and use the public viewport methods only for explicit navigation or layout changes.
1 2 3 4 5 6 7 8 9
readonly trackRecord = (_index: number, record: AuditRecord) => record.id;
readonly viewport = viewChild.required(UiTableVirtualScrollComponent);
this.viewport().scrollToIndex(5_000, 'smooth');
this.viewport().checkViewportSize();
<ui-table-virtual-scroll [rows]="records()" [trackBy]="trackRecord">
<ng-template uiTableVirtualRow let-row>{{ row.title }}</ng-template>
</ui-table-virtual-scroll>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
rows [] readonly T[] Complete ordered dataset virtualized by the fixed-size CDK strategy.
itemSize 48 number Fixed row height in pixels, normalized to at least one.
minBufferPx 192 number Minimum rendered buffer in pixels, never smaller than one row.
maxBufferPx 384 number Maximum rendered buffer in pixels, never smaller than the minimum.
height '24rem' string CSS block size for the focusable scrolling viewport.
ariaLabel 'Virtualized table rows' string Accessible name for the virtual rowgroup.
loading false boolean Marks the viewport busy while preserving already rendered rows.
trackBy null UiTableVirtualTrackBy<T> | null Optional stable identity function; item identity is the fallback.
uiTableVirtualRow optional directive Typed row template exposing row/$implicit and its absolute dataset index.
| Name | Type | Default | Description |
|---|---|---|---|
rows | readonly T[] | [] | Complete ordered dataset virtualized by the fixed-size CDK strategy. |
itemSize | number | 48 | Fixed row height in pixels, normalized to at least one. |
minBufferPx | number | 192 | Minimum rendered buffer in pixels, never smaller than one row. |
maxBufferPx | number | 384 | Maximum rendered buffer in pixels, never smaller than the minimum. |
height | string | '24rem' | CSS block size for the focusable scrolling viewport. |
ariaLabel | string | 'Virtualized table rows' | Accessible name for the virtual rowgroup. |
loading | boolean | false | Marks the viewport busy while preserving already rendered rows. |
trackBy | UiTableVirtualTrackBy<T> | null | null | Optional stable identity function; item identity is the fallback. |
uiTableVirtualRow | directive | optional | Typed row template exposing row/$implicit and its absolute dataset index. |
Outputs
scrolledIndexChange OutputEmitterRef<number> Emits the first visible item index as the viewport scrolls.
| Name | Type | Description |
|---|---|---|
scrolledIndexChange | OutputEmitterRef<number> | Emits the first visible item index as the viewport scrolls. |
Accessibility
- The focusable viewport is a named rowgroup with total aria-rowcount and each mounted item uses row plus its absolute aria-rowindex.
- Virtualization removes off-screen rows from the accessibility tree; offer filtering, search, or pagination when users must navigate the entire dataset predictably.
- loading sets aria-busy without removing the currently rendered context.
Keyboard behavior
- The viewport is keyboard focusable and uses native scrolling keys; interactive controls inside row templates retain their own native keyboard behavior.
Testing guidance
- Assert total row count semantics, bounded rendered DOM, normalized buffers, typed template compilation, busy state, stable tracking, and explicit scroll navigation.