Virtualization
Import
Import TableauUiVirtualizeModule from tableau-ui-angular/virtualize, which also has the data options.
Loading the data
tab-virtualize asks its [dataOptions] for rows, a block at a time. A block is as many rows as the list's height holds, and the list keeps [dataBlockWindow] blocks, 3 by default, loaded on each side of the ones in view.
| Data options | What the loader is asked |
|---|---|
IncrementalDataOptions | For a block, by its offset and count, as the user scrolls to it; it answers the block's rows and the total |
FullDataOptions | For every row, once; the list still draws them a block at a time |
- Both take a function that gives a row's key first.
[dataSort]is required: the sort each request carries,[]for none. The list loads again when it, or the data options, change.- A request's
abortsignal fires once the list no longer needs its rows: after a reset, when the user scrolls a block far from view, or when the list goes. [dataRowCss]gives every row the same height, line height and padding:1.5em,inheritand0em 0.5emby default. The height is the row's content's: a row is drawn that tall plus its vertical padding, and the list keeps that much space for each row not drawn.
The list measures its height and its rows to size a block, so it loads in the browser only: call load() once it is drawn, and reload() when its height changes. reset() loads it again from the first block. A row whose block is loading shows a pulsing bar, and one whose block failed a red bar; tabItemLoadingTemplate and tabItemErrorTemplate replace them.
import { afterNextRender, ChangeDetectionStrategy, Component, computed, signal, viewChild } from '@angular/core';
import { TableauUiButtonModule } from 'tableau-ui-angular/button';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import { TableauUiRadioGroupModule } from 'tableau-ui-angular/radio-group';
import type { DataOptions, FullDataRequest, IncrementalDataRequest } from 'tableau-ui-angular/virtualize';
import { FullDataOptions, IncrementalDataOptions, TableauUiVirtualizeModule, VirtualizeComponent } from 'tableau-ui-angular/virtualize';
interface Row {
id: number;
name: string;
}
// 10,000 rows, the same on every load
const ROWS: Row[] = Array.from({ length: 10_000 }, (_, index) => ({ id: index + 1, name: `Row ${index + 1}` }));
type Answer = 'error' | 'none' | 'rows' | 'two';
@Component({
selector: 'app-virtualize-data-example',
imports: [TableauUiButtonModule, TableauUiCommonModule, TableauUiRadioGroupModule, TableauUiVirtualizeModule],
templateUrl: './virtualize-data.example.html',
styleUrl: './virtualize-data.example.scss',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class VirtualizeDataExampleComponent {
private readonly list = viewChild.required<VirtualizeComponent<Row>>(VirtualizeComponent);
protected readonly $mode = signal<'full' | 'incremental'>('incremental');
// What the loads answer, from the buttons
private readonly $answer = signal<Answer>('rows');
protected readonly $lastRequest = signal('nothing yet');
// The list loads again, from the start, when its data options change
protected readonly $dataOptions = computed<DataOptions<Row>>(() =>
this.$mode() === 'incremental'
? new IncrementalDataOptions<Row>(
row => row.id,
async (request: IncrementalDataRequest) => {
this.$lastRequest.set(`rows ${request.offset + 1} to ${request.offset + request.count}`);
const rows = await this.rows(request.abort);
if (this.$answer() === 'error' && request.offset > 20) {
throw new Error('A block after the 20th row failed');
}
return { data: rows.slice(request.offset, request.offset + request.count), total: rows.length };
},
)
: new FullDataOptions<Row>(
row => row.id,
async (request: FullDataRequest) => {
this.$lastRequest.set('every row');
const rows = await this.rows(request.abort);
if (this.$answer() === 'error') {
throw new Error('The load failed');
}
return { data: rows };
},
),
);
constructor() {
// The list measures its height to know how many rows a block holds, so it loads once it is drawn, in the browser
afterNextRender(() => {
void this.list().load();
});
}
protected show(answer: Answer) {
this.$answer.set(answer);
void this.list().reset();
}
// A server would answer here: the rows come after a second, as from a network, unless a newer load cancels this one
private async rows(abort: AbortSignal): Promise<Row[]> {
await new Promise(resolve => setTimeout(resolve, 1000));
abort.throwIfAborted();
const answer = this.$answer();
if (answer === 'none') {
return [];
}
return answer === 'two' ? ROWS.slice(0, 2) : ROWS;
}
}A list as tall as its rows
The list's own styles give it a max-height of 300px. Without a height, it is as tall as its rows, up to that; before it loads it shows only the no-data template, so [dataWindowHeightPx] gives it the height to size its blocks for in place of measuring.
tabCustomLoadermarks a template that shows in place of the rows while a load waits for its first block.[noDataTemplate]shows while there are no rows, before the first load too: a template, or a message; "No data available" by default.
No rows to show
import { afterNextRender, ChangeDetectionStrategy, Component, signal, viewChild } from '@angular/core';
import { TableauUiButtonModule } from 'tableau-ui-angular/button';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import type { IncrementalDataRequest } from 'tableau-ui-angular/virtualize';
import { IncrementalDataOptions, TableauUiVirtualizeModule, VirtualizeComponent } from 'tableau-ui-angular/virtualize';
interface Row {
id: number;
name: string;
}
const ROWS: Row[] = Array.from({ length: 10_000 }, (_, index) => ({ id: index + 1, name: `Row ${index + 1}` }));
@Component({
selector: 'app-virtualize-height-example',
imports: [TableauUiButtonModule, TableauUiCommonModule, TableauUiVirtualizeModule],
templateUrl: './virtualize-height.example.html',
styleUrl: './virtualize-height.example.scss',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class VirtualizeHeightExampleComponent {
private readonly list = viewChild.required<VirtualizeComponent<Row>>(VirtualizeComponent);
// How many rows the loads answer, from the buttons
private readonly $count = signal(2);
// The rows come after a second, as from a network, unless a newer load cancels this one
protected readonly dataOptions = new IncrementalDataOptions<Row>(
row => row.id,
async (request: IncrementalDataRequest) => {
await new Promise(resolve => setTimeout(resolve, 1000));
request.abort.throwIfAborted();
const rows = ROWS.slice(0, this.$count());
return { data: rows.slice(request.offset, request.offset + request.count), total: rows.length };
},
);
constructor() {
afterNextRender(() => {
void this.list().load();
});
}
protected show(count: number) {
this.$count.set(count);
void this.list().reset();
}
}Accessibility
The list scrolls in its own host, which is in the Tab order, so the keyboard scrolls it in every browser, even when its rows hold nothing that takes focus.
- A list that scrolls needs
label, which names it for screen readers. A staticaria-labelontab-virtualizenames it the same way, andlabelwins. - A static
tabindex="-1"ontab-virtualizetakes it out of the Tab order, as for a short list whose rows hold controls of their own. Atabindexan app put on a wrapper so the keyboard could scroll the list can go. - Once the host has focus, the arrow keys, Page Up, Page Down, Home and End scroll it, and the blocks they reach load.
- While it shows rows, the host is a list and each row a list item with its place in the whole list, as "61 of 10,000". Until the first block says the total, its size is
-1, unknown. - While it shows no rows, its no-data template or its custom loader, the host is a region of its name, and without a name it has no role.
- A row whose block failed shows a red bar, which a screen reader reads as "Failed to load".
- When the rows have a role of their own, such as options, write a static
roleontab-virtualize, such asrole="listbox". The host keeps it, and the rows take no role. The role is read once, when the list is made, so a bound[attr.role]isn't read.
A virtual component of your own
The list and the table extend VirtualizeBaseComponent, which holds the loading and load(), reload() and reset(). A component that extends it gives its data options, its row CSS, its block window and its sort, and measures its window's height.