Tableau UI for Angular

Virtualization

A virtual list draws only the rows near the view, so it holds thousands of rows; the app's loader gives it the data.

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 optionsWhat the loader is asked
IncrementalDataOptionsFor a block, by its offset and count, as the user scrolls to it; it answers the block's rows and the total
FullDataOptionsFor 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 abort signal 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, inherit and 0em 0.5em by 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.

Load
No data available
The last request asked for nothing yet
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.

  • tabCustomLoader marks 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 static aria-label on tab-virtualize names it the same way, and label wins.
  • A static tabindex="-1" on tab-virtualize takes it out of the Tab order, as for a short list whose rows hold controls of their own. A tabindex an 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 role on tab-virtualize, such as role="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.