API Reference

The pagination and skeleton features (page, pageSize, loading, pageNeeded, pageChanged, scrollToPage, ngxVirtualGridSkeleton) require 22.1.0+, 21.1.0+, 20.1.0+, or 19.1.0+.

Inputs

Input	Type	Default	Description
`items`	`unknown[]`	`[]`	Array of data items to render
`bufferSize`	`number`	`3`	Number of extra rows to render above and below the viewport
`loadMoreThreshold`	`number`	`0.8`	Scroll ratio (0-1) at which the `loadMore` event fires. Measured within the loaded data (skeletons and unloaded pages above are excluded), so deep-linked pages don't fire immediately.
`scrollParent`	`HTMLElement \| null`	`null`	Custom scroll container. Uses `window` if `null`
`page`	`number`	`0`	The page (0-indexed) that the first item in `items` belongs to. Keep it set to the lowest loaded page - it creates `page * pageSize` items of virtual space above the loaded data.
`pageSize`	`number`	`0`	Number of items per page. Enables pagination when > 0. Space above loaded data is calculated from `page * pageSize`.
`loading`	`boolean`	`false`	When `true` and a skeleton template is provided, renders skeleton placeholders in visible slots that don't have data. The skeleton count matches the number of items the virtual scroller would normally render.

Outputs

Output	Type	Description
`loadMore`	`void`	Emits when the scroll position crosses the `loadMoreThreshold` within the loaded data. Re-arms when more items are appended; prepending an earlier page does not re-arm it.
`pageNeeded`	`number`	Asks for earlier pages: emits `page - 1` when the viewport nears the top of loaded data, or the viewport's own page after a fast scroll jumps above it. Asks again on each `page` change until the viewport is covered. Use `loadMore` for pages below.
`pageChanged`	`number`	Emits the current page number when the viewport center crosses a page boundary. Useful for updating the URL.

Methods

Method	Description
`scrollToIndex(index: number)`	Scroll to bring the item at the given index into view
`scrollToOffset(pixels: number)`	Scroll to an absolute pixel offset within the grid
`scrollToPage(page: number)`	Scroll to the start of the given page (requires `pageSize` > 0)
`refresh()`	Re-measure dimensions and recalculate layout

Template Context

The ngxVirtualGridItem template receives the following context:

Variable	Type	Description
`$implicit`	`T`	The data item
`index`	`number`	The item's global index. Same as the array index in non-paginated mode; offset by `page * pageSize` in paginated mode

Skeleton Template

Provide a skeleton template using the ngxVirtualGridSkeleton directive. When the loading input is true, skeleton placeholders are rendered in visible slots that don't have data. The library automatically calculates the correct number of skeletons to fill the viewport.

<ngx-virtual-grid [items]="items" [loading]="isLoading">
  <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>

The ngxVirtualGridSkeleton template receives $implicit as the global index of the skeleton slot.

Zoneless Apps

The library works with both zoned and zoneless Angular apps. In zoneless mode, the loadMore output emits from a raw scroll event listener. If your handler modifies component state, use signals so the view updates:

items = signal<Item[]>([]);

onLoadMore(): void {
  this.items.update(current => [...current, ...newItems]);
}