ng-table-virtual-scroll

Install the package using npm to enable virtual scrolling for Angular Material tables.

Version Compatibility:

• Angular >= 15: Use latest version.
• Angular 13 - 14: Use 1.5.* version.
• Angular <= 12: Use 1.3.* version.

$ npm install -save ng-table-virtual-scroll

To use the library, import TableVirtualScrollModule into your Angular module.

Prerequisites: You must have already installed and configured @angular/cdk/scrolling (ScrollingModule) and @angular/material/table (MatTableModule). TableVirtualScrollModule is designed to make these two modules work together.

import { TableVirtualScrollModule } from 'ng-table-virtual-scroll';

@NgModule({
  imports: [
    // ...
    TableVirtualScrollModule
  ]
})
export class AppModule { }

When working with virtual scrolling in ng-table-virtual-scroll, your data source should implement the TVSDataSource<T> interface. This interface provides two essential RxJS Subjects that facilitate the communication between your data and the virtual scroll engine:

• dataToRender$: A Subject<T[]> that emits the subset of data currently intended to be rendered in the table rows.
• dataOfRange$: A Subject<T[]> used to signal the specific range of data that the virtual scroller should provide to the table's internal rendering stream.

To use the virtual scroll functionality in your Angular application, import the TableVirtualScrollModule into your Angular module (e.g., app.module.ts). This module exports the TableItemSizeDirective, which is required to configure item sizes for the virtual scroll mechanism.

import { TableVirtualScrollModule } from 'ng-table-virtual-scroll';

@NgModule({
  imports: [
    TableVirtualScrollModule,
    // ... other imports
  ],
  // ...
})
export class AppModule { }

The directive requires a specific data source to function. You must use TableVirtualScrollDataSource (which extends MatTableDataSource) for mat-table.

If you are using cdk-table instead of mat-table, use CdkTableVirtualScrollDataSource.

import { TableVirtualScrollDataSource } from 'ng-table-virtual-scroll';

@Component({...})
export class MyComponent {
  dataSource = new TableVirtualScrollDataSource();
}

The TableItemSizeDirective enforces strict data source types to ensure the virtual scroll strategy can correctly calculate the rendered range. If you provide an incompatible data source, you will encounter the following errors:

• For mat-table: [tvsItemSize] requires TableVirtualScrollDataSource be set as [dataSource] of [mat-table]
• For cdk-table: [tvsItemSize] requires CdkTableVirtualScrollDataSource be set as [dataSource] of [cdk-table]
• General: [tvsItemSize] requires TableVirtualScrollDataSource or CdkTableVirtualScrollDataSource be set as [dataSource] of the table

The FixedSizeTableVirtualScrollStrategy provides several observable streams and properties to track the state of the virtualized table:

• dataLength: A getter/setter to manage the total number of items in the data set. Setting this value updates the total content size of the viewport.
• scrolledIndexChange: An Observable<number> that emits the index of the currently displayed row when the user scrolls.
• renderedRangeStream: A BehaviorSubject<ListRange> that provides the current range of rendered items {start, end}.
• stickyChange: A Subject<number> that emits the adjusted rendered offset, useful for managing sticky elements.

You can programmatically scroll the table to a specific row index using the scrollToIndex method. This method calculates the offset based on the configured rowHeight and headerHeight.

// Scrolls to the row at index 10
strategy.scrollToIndex(10);

// Scrolls to index 10 with smooth behavior
strategy.scrollToIndex(10, 'smooth');

Use CdkTableVirtualScrollDataSource<T> when you are using a standard Angular CDK DataSource and want to add virtual scrolling capabilities. It extends the base DataSource<T> and implements TVSDataSource<T>.

Key features:

• Data Management: You can set the source data using the data property (e.g., dataSource.data = myItems;).
• Stream Initialization: The class manages internal subscriptions to ensure dataToRender$ and dataOfRange$ are ready for use.
• Lifecycle: It implements connect() and disconnect() as required by the CDK DataSource contract.

To configure the virtual scroll strategy, use the setConfig method with a TSVStrategyConfigs object. This allows you to define the dimensions of the table components and the buffering behavior. Changing these values will trigger an update to the content size calculation.

strategy.setConfig({
  rowHeight: 50,
  headerHeight: 100,
  footerHeight: 50,
  bufferMultiplier: 2
});