Getting Started

Installation

npm install @theryansmee/ngx-virtual-grid

yarn add @theryansmee/ngx-virtual-grid

pnpm add @theryansmee/ngx-virtual-grid

Angular Version Support

Each Angular major version is maintained on its own branch with a matching npm tag.

Pagination and skeleton loading are newer features - they need the minimum library version shown above and are not available on the Angular 14-18 branches.

To install a specific Angular version:

npm install @theryansmee/ngx-virtual-grid

Basic Usage

Import the component and directive directly:

import { Component } from '@angular/core';
import { NgxVirtualGridComponent, VirtualGridItemDirective } from '@theryansmee/ngx-virtual-grid';

@Component({
  selector: 'app-example',
  imports: [NgxVirtualGridComponent, VirtualGridItemDirective],
  template: `
    <ngx-virtual-grid
      [items]="items"
      [bufferSize]="3"
      [loadMoreThreshold]="0.8"
      (loadMore)="onLoadMore()">

      <ng-template ngxVirtualGridItem let-item let-index="index">
        <div class="card">{{ item.name }}</div>
      </ng-template>
    </ngx-virtual-grid>
  `,
  styles: [`
    ngx-virtual-grid {
      grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
      gap: 16px;
    }
  `],
})
export class ExampleComponent {
  items: any[] = [];

  onLoadMore(): void {
    // Fetch and append more items
  }
}

The component works as a CSS Grid container. You control the layout with standard grid-template-columns and gap properties. See the Layouts page for more examples.

Skeleton Loading

Requires 22.1.0+, 21.1.0+, 20.1.0+, or 19.1.0+.

Real apps have network latency. Provide a skeleton template with the ngxVirtualGridSkeleton directive and bind loading - the library renders the right number of placeholders to fill the visible area while data is in flight.

<ngx-virtual-grid [items]="items" [loading]="isLoading" (loadMore)="onLoadMore()">
  <ng-template ngxVirtualGridItem let-item>
    <app-card [data]="item"></app-card>
  </ng-template>

  <ng-template ngxVirtualGridSkeleton>
    <app-card-skeleton></app-card-skeleton>
  </ng-template>
</ngx-virtual-grid>

Pagination

Requires 22.1.0+, 21.1.0+, 20.1.0+, or 19.1.0+.

For paginated APIs and deep-linking (e.g. ?page=8), set page to the lowest loaded page and pageSize to the items per page. The library creates virtual space above the loaded data, emits loadMore to append pages below, pageNeeded to prepend pages above, and pageChanged as the user scrolls between pages.

<ngx-virtual-grid
  [items]="items"
  [page]="firstLoadedPage"
  [pageSize]="pageSize"
  [loading]="isLoading"
  (loadMore)="onLoadMore()"
  (pageNeeded)="onPageNeeded($event)"
  (pageChanged)="onPageChanged($event)">
  ...
</ngx-virtual-grid>

The expected data-loading pattern:

• onLoadMore() - append the next page and set isLoading = true while it's in flight
• onPageNeeded(page) - prepend pages down to page and update firstLoadedPage
• onPageChanged(page) - update the URL so the position survives a refresh
• Use scrollToPage(page) after the initial data arrives to position a deep-linked user

See the Pagination demo for a working example and the API reference for exact emission behavior.