ngx-virtual-grid

A responsive virtual-scrolling grid for Angular. Fixed-size items, auto-measured dimensions, CSS Grid layout.

Live Demo | GitHub | npm

Features

• Virtual scrolling with CSS Grid layout
• Auto-measures item dimensions from the first rendered row
• Responsive — adapts to column count changes via CSS
• Infinite scroll with configurable threshold
• SSR-safe (no DOM access during server-side rendering)

Installation

npm install @theryansmee/ngx-virtual-grid

yarn add @theryansmee/ngx-virtual-grid

Angular Version Support

Each Angular major version is maintained on its own branch:

The main branch tracks the latest stable version.

Usage

Standalone imports (recommended)

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

@Component({
  selector: 'app-example',
  standalone: true,
  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 {
    // Load more items...
  }
}

NgModule (deprecated)

import { NgxVirtualGridModule } from '@theryansmee/ngx-virtual-grid';

@NgModule({
  imports: [NgxVirtualGridModule],
})
export class AppModule {}

Note: NgxVirtualGridModule is deprecated and will be removed in v19. Use standalone imports instead.

Grid layout

The component renders as a CSS Grid container. Control the number and size of columns with standard CSS on the <ngx-virtual-grid> element:

ngx-virtual-grid {
  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
  gap: 16px;
}

The library auto-detects the column count and row height from the computed grid layout.

Custom scroll parent

By default the component listens for scroll events on window. To use a custom scroll container, pass it via the scrollParent input:

<div #scrollContainer style="height: 600px; overflow-y: auto;">
  <ngx-virtual-grid [items]="items" [scrollParent]="scrollContainer">
    ...
  </ngx-virtual-grid>
</div>

API

Inputs

Outputs

Methods

Template context

The ngxVirtualGridItem template receives:

License

MIT