Component v1.1.0 Navigation/Data

Table Virtual Scroll

Optional Angular CDK-powered fixed-size row virtualization for large datasets with typed templates and bounded DOM rendering.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-table-virtual-scroll
Package
@ngnova/ui/table-virtual-scroll

Import

Standalone Tailwind v4
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.

API Reference

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.

Angular template ui-table-virtual-scroll-recipe.example.html
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.

Angular template ui-table-virtual-scroll-recipe.example.html
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.

Outputs

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.