NgVirtualList

🚀 High-performance virtual scrolling for Angular apps. Render 10,000+ items in Angular without breaking a sweat. Smooth, customizable, and developer-friendly.

⚡A powerful API for implementing lists of varying functionality and complexity.

✨Flexible, and actively maintained Angular library that excels with high-performance, feature-rich virtualized lists—including grouping, sticky headers, snapping, animations, collapsing group elements, single and multiple selection of elements and both scroll directions, lists with scrolling bindings for elements, galleries of varying complexity, including 3D transformations of elements and effects such as MotionBlur, DOF ​​(Depth Of Field) and Fog. Whether you're rendering millions of items or building interactive list components, it delivers scalability and customization. Angular (14–22) compatibility.

🧬The main advantage of this solution is the elimination of the "empty spaces" effect during fast scrolling, which occurs in the classic implementation of virtualized lists. Visualization is as close as possible to native lists.

💻 Works correctly in all browsers and platforms.

💪 The software portion of the project was completed without a single line of code written using AI (artificial intelligence)!

Angular version 22.X.X.

Documentation

✨ Why use ng-virtual-list?

⚡ Blazing fast — only renders what’s visible (plus a smart buffer).
📱 Works everywhere — smooth on desktop & mobile.
🔀 Flexible layouts — vertical, horizontal, grouped lists, sticky headers.
📏 Dynamic sizes — handles items of varying height/width.
🔍 Precise control — scroll to an ID, or snap to positions.
✅ Selecting elements — ability to work in Select and MultiSelect modes.
🧩 Collapsing group elements — ability to collapse group elements (elements with the "stickiness" parameter).

⚙️ Key Features

Virtualization modes

• Fixed size (fastest)
  • Dynamic size (auto-measured)
  • Scrolling control
• Scroll to item ID
  • Smooth or instant scroll
  • Custom snapping behavior
• Advanced layouts
  • Grouped lists with sticky headers
  • Horizontal or vertical scrolling
• Selecting elements
  • Single selection
  • Multiple selection
• Performance tuning
  • bufferSize and maxBufferSize for fine-grained control
• Collapsing groups
  • collapse group elements

📱 When to Use It: Ideal Use Cases

Drawing on general virtual-scroll insights and ng-virtual-list features:

Long-Scrolling Lists / Live Feeds When displaying hundreds of thousands of items (think social media feeds, chat logs, or news streams), ng-virtual-list ensures smooth and responsive rendering without overwhelming the browser.

Horizontal Carousels or Galleries Ideal for media-rich UI elements like image galleries, product cards, or horizontal scrollers where traditional ngFor rendering becomes sluggish.

Grouped Navigation with Section Headers For catalogs, logs, or grouped entries (e.g., by date or category), you can use sticky headers and snapping to guide user navigation effectively.

"Jump to" Item Navigation Use cases like directories or chat histories benefit from the ability to scroll directly to specific items by ID.

Complex or Rich-Content Templates As each item may contain images, nested components, or interactions, virtual rendering keeps performance intact even when item complexity increases.

Single and multiple selection of elements

Navigating with the keyboard

Collapsing groups

Support for element animation

Implemented a virtual scroll handler, ensuring stable scrolling on all platforms

📦 Installation

npm i ng-virtual-list

🚀 Quick Start

<ng-virtual-list [items]="items" [bufferSize]="5" [itemRenderer]="itemRenderer" [dynamicSize]="false" [itemSize]="64"></ng-virtual-list>

<ng-template #itemRenderer let-data="data">
  @if (data) {
      <span>{{data.name}}</span>
  }
</ng-template>

items = Array.from({ length: 100000 }, (_, i) => ({ id: i, name: `Item #${i}` }));

📱 Examples

Horizontal virtual list (Single selection)

Template:

<ng-virtual-list class="list" direction="horizontal" [items]="horizontalItems" [bufferSize]="1" [maxBufferSize]="5"
    [itemRenderer]="horizontalItemRenderer" [dynamicSize]="false" [itemSize]="64" [selectingMode]="'select'"
    [selectedIds]="2" (onSelect)="onSelect($event)" (onItemClick)="onItemClick($event)"></ng-virtual-list>

<ng-template #horizontalItemRenderer let-data="data" let-config="config">
  @if (data) {
    <div [ngClass]="{'list__h-container': true, 'selected': api.selected}">
      <span>{{data.name}}</span>
    </div>
  }
</ng-template>

Component:

import { NgVirtualListComponent, IVirtualListCollection, IRenderVirtualListItem } from 'ng-virtual-list';

interface ICollectionItem {
  name: string;
}

const HORIZONTAL_ITEMS: IVirtualListCollection<ICollectionItem> = Array.from({ length: 100000 }, (_, i) => ({ id: i, name: `${i}` }));

@Component({
  selector: 'app-root',
  imports: [NgVirtualListComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss'
})
export class AppComponent {
  horizontalItems = HORIZONTAL_ITEMS;

  onItemClick(item: IRenderVirtualListItem<ICollectionItem> | null) {
    if (item) {
      console.info(`Click: (ID: ${item.id}) Item ${item.data.name}`);
    }
  }

  onSelect(data: Array<Id> | Id | null) {
    console.info(`Select: ${JSON.stringify(data)}`);
  }
}

Horizontal grouped virtual list (Multiple selection)

Template:

<ng-virtual-list class="list" direction="horizontal" [items]="horizontalGroupItems" [itemRenderer]="horizontalGroupItemRenderer"
    [bufferSize]="1" [maxBufferSize]="5" [itemConfigMap]="horizontalGroupItemConfigMap" [dynamicSize]="false" [itemSize]="54" [stickyEnabled]="true" selectingMode="multi-select" [selectedIds]="[3,2]" (onSelect)="onSelect($event)" (onItemClick)="onItemClick($event)"></ng-virtual-list>

<ng-template #horizontalGroupItemRenderer let-data="data" let-config="config">
  @if (data) {
    @switch (data.type) {
      @case ("group-header") {
        <div class="list__h-group-container">
          <span>{{data.name}}</span>
        </div>
      }
      @default {
        <div [ngClass]="{'list__h-container': true, 'selected': api.selected}">
          <span>{{data.name}}</span>
        </div>
      }
    }
  }
</ng-template>

Component:

import { NgVirtualListComponent, IVirtualListCollection, IVirtualListItemConfigMap, IRenderVirtualListItem } from 'ng-virtual-list';

const GROUP_NAMES = ['A', 'B', 'C', 'D', 'E'];

const getGroupName = () => {
  return GROUP_NAMES[Math.floor(Math.random() * GROUP_NAMES.length)];
};

interface ICollectionItem {
  type: 'group-header' | 'item';
  name: string;
}

const HORIZONTAL_GROUP_ITEMS: IVirtualListCollection<ICollectionItem> = [],
  HORIZONTAL_GROUP_ITEM_CONFIG_MAP: IVirtualListItemConfigMap = {};

for (let i = 0, l = 1000000; i < l; i++) {
  const id = i + 1, type = Math.random() > .895 ? 'group-header' : 'item';
  HORIZONTAL_GROUP_ITEMS.push({ id, type, name: type === 'group-header' ? getGroupName() : `${i}` });
  HORIZONTAL_GROUP_ITEM_CONFIG_MAP[id] = type === 'group-header' ? 1 : 0;
}

@Component({
  selector: 'app-root',
  imports: [NgVirtualListComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss'
})
export class AppComponent {
  horizontalGroupItems = HORIZONTAL_GROUP_ITEMS;
  horizontalGroupItemConfigMap = HORIZONTAL_GROUP_ITEM_CONFIG_MAP;

  onItemClick(item: IRenderVirtualListItem<ICollectionItem> | null) {
    if (item) {
      console.info(`Click: (ID: ${item.id}) Item ${item.data.name}`);
    }
  }

  onSelect(data: Array<Id> | Id | null) {
    console.info(`Select: ${JSON.stringify(data)}`);
  }
}

Vertical virtual list

Template:

<ng-virtual-list class="list simple" [items]="items" [bufferSize]="1" [maxBufferSize]="5" [itemRenderer]="itemRenderer"
  [dynamicSize]="false" [itemSize]="40"></ng-virtual-list>

<ng-template #itemRenderer let-data="data">
  @if (data) {
    <div class="list__container">
      <p>{{data.name}}</p>
    </div>
  }
</ng-template>

Component:

import { NgVirtualListComponent, IVirtualListCollection } from 'ng-virtual-list';

const ITEMS: IVirtualListCollection = [];

for (let i = 0, l = 100000; i < l; i++) {
  ITEMS.push({ id: i, name: `Item: ${i}` });
}

@Component({
  selector: 'app-root',
  imports: [NgVirtualListComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss'
})
export class AppComponent {
  items = ITEMS;
}

Vertical grouped virtual list

Without snapping

Template:

<ng-virtual-list class="list simple" [items]="groupItems" [bufferSize]="1" [maxBufferSize]="5" [itemRenderer]="groupItemRenderer"
    [itemConfigMap]="groupItemConfigMap" [dynamicSize]="false" [itemSize]="40" [stickyEnabled]="false"></ng-virtual-list>

<ng-template #groupItemRenderer let-data="data">
  @if (data) {
    @switch (data.type) {
      @case ("group-header") {
        <div class="list__group-container">
          <p>{{data.name}}</p>
        </div>
      }
      @default {
        <div class="list__container">
          <p>{{data.name}}</p>
        </div>
      }
    }
  }
</ng-template>

With snapping

Template (with snapping):

<ng-virtual-list class="list simple" [items]="groupItems" [bufferSize]="1" [maxBufferSize]="5" [itemRenderer]="groupItemRenderer"
    [itemConfigMap]="groupItemConfigMap" [dynamicSize]="false" [itemSize]="40" [stickyEnabled]="true"></ng-virtual-list>

<ng-template #groupItemRenderer let-data="data">
  @if (data) {
    @switch (data.type) {
      @case ("group-header") {
        <div class="list__group-container">
          <p>{{data.name}}</p>
        </div>
      }
      @default {
        <div class="list__container">
          <p>{{data.name}}</p>
        </div>
      }
    }
  }
</ng-template>

Component:

import { NgVirtualListComponent, IVirtualListCollection, IVirtualListItemConfigMap } from 'ng-virtual-list';

const GROUP_ITEMS: IVirtualListCollection = [],
  GROUP_ITEM_CONFIG_MAP: IVirtualListItemConfigMap = {};

let groupIndex = 0;
for (let i = 0, l = 10000000; i < l; i++) {
  const id = i, type = Math.random() > .895 ? 'group-header' : 'item';
  if (type === 'group-header') {
    groupIndex++;
  }
  GROUP_ITEMS.push({ id, type, name: type === 'group-header' ? `Group ${groupIndex}` : `Item: ${i}` });
  GROUP_ITEM_CONFIG_MAP[id] = type === 'group-header' ? 1 : 0;
}

@Component({
  selector: 'app-root',
  imports: [NgVirtualListComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss'
})
export class AppComponent {
  groupItems = GROUP_ITEMS;
  groupItemConfigMap = GROUP_ITEM_CONFIG_MAP;
}

ScrollTo

The example demonstrates the scrollTo method by passing it the element id. It is important not to confuse the ordinal index and the element id. In this example, id = index + 1

Template

<div class="scroll-to__controls">
  <input type="number" class="scroll-to__input" [(ngModel)]="itemId" [required]="true" [min]="items[0].id"
    [max]="items[items.length - 1].id">
  <button class="scroll-to__button" (click)="onButtonScrollToIdClickHandler($event)">Scroll</button>
</div>

<ng-virtual-list #virtualList class="list" [items]="items" [itemRenderer]="itemRenderer" [bufferSize]="1" [maxBufferSize]="5"
  [dynamicSize]="false" [itemSize]="40"></ng-virtual-list>

<ng-template #itemRenderer let-data="data">
@if (data) {
  <div class="list__container">
    <span>{{data.name}}</span>
  </div>
}
</ng-template>

Component

import { NgVirtualListComponent, IVirtualListCollection, Id } from 'ng-virtual-list';

const MAX_ITEMS = 1000000;

const ITEMS: IVirtualListCollection = [];
for (let i = 0, l = MAX_ITEMS; i < l; i++) {
  ITEMS.push({ id: i + 1, name: `Item: ${i}` });
}

@Component({
  selector: 'app-root',
  imports: [FormsModule, NgVirtualListComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss'
})
export class AppComponent {
  protected _listContainerRef = viewChild('virtualList', { read: NgVirtualListComponent });

  items = ITEMS;

  itemId: Id = this.items[0].id;

  onButtonScrollToIdClickHandler = (e: Event) => {
    const list = this._listContainerRef();
    if (list) {
      list.scrollTo(this.itemId, 'smooth');
    }
  }
}

Virtual list (with dynamic item size)

Virtual list with height-adjustable elements.

Template

<ng-virtual-list #dynamicList class="list" [items]="groupDynamicItems" [itemRenderer]="groupItemRenderer" [bufferSize]="1" [maxBufferSize]="5"
      [itemConfigMap]="groupDynamicItemConfigMap" [stickyEnabled]="true"></ng-virtual-list>

<ng-template #groupItemRenderer let-data="data">
  @if (data) {
    @switch (data.type) {
      @case ("group-header") {
        <div class="list__group-container">
          <span>{{data.name}}</span>
        </div>
      }
      @default {
        <div class="list__container">
          <span>{{data.name}}</span>
        </div>
      }
    }
  }
</ng-template>

Component

import { NgVirtualListComponent, IVirtualListCollection } from 'ng-virtual-list';

const CHARS = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'];

const generateLetter = () => {
  return CHARS[Math.round(Math.random() * CHARS.length)];
}

const generateWord = () => {
  const length = 5 + Math.floor(Math.random() * 50), result = [];
  while (result.length < length) {
    result.push(generateLetter());
  }
  return `${result.join('')}`;
};

const generateText = () => {
  const length = 2 + Math.floor(Math.random() * 10), result = [];
  while (result.length < length) {
    result.push(generateWord());
  }
  result[0] = result[0].toUpperCase();
  return `${result.join(' ')}.`;
};

const GROUP_DYNAMIC_ITEMS: IVirtualListCollection = [],
  GROUP_DYNAMIC_ITEM_CONFIG_MAP: IVirtualListItemConfigMap = {};

let groupDynamicIndex = 0;
for (let i = 0, l = 100000; i < l; i++) {
  const id = i + 1, type = i === 0 || Math.random() > .895 ? 'group-header' : 'item';
  if (type === 'group-header') {
    groupDynamicIndex++;
  }
  GROUP_DYNAMIC_ITEMS.push({ id, type, name: type === 'group-header' ? `Group ${groupDynamicIndex}` : `${id}. ${generateText()}` });
  GROUP_DYNAMIC_ITEM_CONFIG_MAP[id] = type === 'group-header' ? 1 : 0;
}

@Component({
  selector: 'app-root',
  imports: [FormsModule, NgVirtualListComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss'
})
export class AppComponent {
  groupDynamicItems = GROUP_DYNAMIC_ITEMS;
  groupDynamicItemConfigMap = GROUP_DYNAMIC_ITEM_CONFIG_MAP;
}

🖼️ Stylization

Scrollbar stylization

.list::part(scrollbar-thumb__shape) {
    background-color: rgba(51, 0, 97, 1);
    border-radius: 3px;
}

<ng-virtual-list class="list" [scrollbarThickness]="12" [items]="items" [itemRenderer]="itemRenderer"></ng-virtual-list>

<ng-template #itemRenderer let-data="data" let-config="config">
  <span>{{data.name}}</span>
</ng-template>

Scrollbar castomization

Examples CustomScrollbarComponent

List items are encapsulated in shadowDOM, so to override default styles you need to use ::part access

• Customize a scroll area of list

.list {
    border-radius: 3px;
    box-shadow: 1px 2px 8px 4px rgba(0, 0, 0, 0.075);
    border: 1px solid rgba(0, 0, 0, 0.1);
}

• Set up the list item canvas

.list::part(list) {
    background-color: #ffffff;
}

• Set up the snapped item (Only SnappingMethod.ADVANCED)

.list::part(snapped-item) {
    color: #71718c;
}

• Set up the list item

.list::part(item) {
    background-color: unset; // override default styles
}

Selecting even elements:

<ng-virtual-list class="list" direction="horizontal" [items]="horizontalItems" [bufferSize]="1" [maxBufferSize]="5"
  [itemRenderer]="horizontalItemRenderer" [itemSize]="54"></ng-virtual-list>

<ng-template #horizontalItemRenderer let-data="data" let-config="config">
  @if (data) {
    <div [ngClass]="{'item-container': true, 'even': config.even}">
      <span>{{data.name}}</span>
    </div>
  }
</ng-template>

.item-container {
  &.even {
      background-color: #1d1d21;
  }
}

📚 API

NgVirtualListComponent

Inputs

Property	Type	Description
alignment	Alignment	Determines the alignment of the list. Two modes are available: none and center. The center mode aligns the list items to the center of the viewport, ideal for use with the itemTransform property. The none mode means no alignment. The default value is none.
animationParams	IAnimationParams? = { scrollToItem: 150, snapToItem: 150, navigateToItem: 150, navigateByKeyboard: 50 }	Animation parameters. The default value is "{ scrollToItem: 150, snapToItem: 150, navigateToItem: 150, navigateByKeyboard: 50 }".
bufferSize	number? = 2	Number of elements outside the scope of visibility. Default value is 2.
clickDistance	number? = 40	The maximum scroll distance at which a click event is triggered.
collapsedIds	Array<Id>	Sets the collapsed items.
collapseByClick	boolean? = true	If false, the element is collapsed using the config.collapse method passed to the template; if true, the element is collapsed by clicking on it. The default value is true.
collapsingMode	CollapsingMode	Mode for collapsing list items. Default value is none. none - List items are not selectable. multi-collapse - List items are collapsed one by one. 'accordion' - Accordion collapsible list items. Default value is multi-collapse.
collectionMode	CollectionMode? = 'normal'	Determines the action modes for collection elements. Default value is normal.
divides	number = 1	Column or row numbers. The default value is 1.
direction	Direction? = 'vertical'	Determines the direction in which elements are placed. Default value is "vertical".
dynamicSize	boolean? = true	If true, items in the list may have different sizes, and the itemSize property must be specified to adjust the sizes of items in the unallocated area. If false then the items in the list have a fixed size specified by the itemSize property. The default value is true.
enabledBufferOptimization	boolean? = false	Experimental! Enables buffer optimization. Can only be used if items in the collection are not added or updated.
id	number	Readonly. Returns the unique identifier of the component.
items	IVirtualListCollection	Collection of list items. The collection of elements must be immutable.
itemSize	number | 'viewport' = 24	If direction = 'vertical', then the height of a typical element. If direction = 'horizontal', then the width of a typical element. If the dynamicSize property is true, the items in the list can have different sizes, and you must specify the itemSize property to adjust the sizes of the items in the unallocated area. If the value is 'viewport', the sizes of elements are automatically resized to fit the viewport size.
itemTransform	ItemTransform | null = null	Custom transformation of element's position, rotation, scale, opacity and zIndex. The default value is null.
itemRenderer	TemplateRef	Rendering element template.
itemConfigMap	IVirtualListItemConfigMap?	Sets sticky position, fullSize, collapsable and selectable for the list item element. If sticky position is greater than 0, then sticky position is applied. If the sticky value is greater than 0, then the sticky position mode is enabled for the element. 1 - position start, 2 - position end. Default value is 0. selectable determines whether an element can be selected or not. Default value is true. collapsable determines whether an element with a sticky property greater than zero can collapse and collapse elements in front that do not have a sticky property. fullSize determines the size of an element when rendering lists with cell divisions. If sticky is 1 or 2, fullSize automatically becomes true. The default value is false.
langTextDir	TextDirection? = 'ltr'	A string indicating the direction of text for the locale. Can be either "ltr" (left-to-right) or "rtl" (right-to-left).
loading	boolean? = false	If true, the scrollBar goes into loading state. The default value is false.
maxBufferSize	number? = 10	Maximum number of elements outside the scope of visibility. Default value is 10. If maxBufferSize is set to be greater than bufferSize, then adaptive buffer mode is enabled. The greater the scroll size, the more elements are allocated for rendering.
maxMotionBlur	number = 0.5	Maximum motion blur effect. The default value is 0.5.
selectingMode	SelectingMode	Method for selecting list items. Default value is 'none'. 'select' - List items are selected one by one. 'multi-select' - Multiple selection of list items. 'none' - List items are not selectable.
minItemSize	number | 'viewport' = 1	If the dynamicSize property is enabled, the minimum size of the element is set. If the value is 'viewport', the sizes of elements are automatically resized to fit the viewport size.
maxItemSize	number | 'viewport' = Number.MAX_SAFE_INTEGER	If the dynamicSize property is enabled, the maximum size of the element is set. If the value is 'viewport', the sizes of elements are automatically resized to fit the viewport size.
motionBlur	number | 'disabled' = 0.15	Motion blur effect. The default value is 0.25.
motionBlurEnabled	boolean = false	Determines whether to apply motion blur or not. The default value is false.
overscrollEnabled	boolean? = true	Determines whether the overscroll (re-scroll) feature will work. The default value is "true".
overlappingScrollbar	boolean? = false	Determines whether the scroll bar will overlap the list. The default value is "false".
selectByClick	boolean? = true	If false, the element is selected using the config.select method passed to the template; if true, the element is selected by clicking on it. The default value is true.
stickyEnabled	boolean? = false	Determines whether items with the given sticky in itemConfigMap will stick to the edges. Default value is "false".
selectedIds	Array<Id> | Id | null	Sets the selected items.
screenReaderMessage	string? = "Showing items $1 to $2"	Message for screen reader. The message format is: "some text $1 some text $2", where $1 is the number of the first element of the screen collection, $2 is the number of the last element of the screen collection.
waitForPreparation	boolean? = true	If true, it will wait until the list items are fully prepared before displaying them.. The default value is true.
scrollStartOffset	FloatOrPersentageValue = 0	Sets the scroll start offset value. Can be specified in absolute or percentage values. Supports arithmetic expressions of addition 50% + 25 or subtraction 50% - 25. Default value is "0".
scrollEndOffset	FloatOrPersentageValue = 0	Sets the scroll end offset value. Can be specified in absolute or percentage values. Supports arithmetic expressions of addition 50% + 25 or subtraction 50% - 25. Default value is "0".
snapToItem	boolean = false	Snap to an item. The default value is false.
snapToItemAlign	SnapToItemAlign = SnapToItemAligns.CENTER	Alignment for snapToItem. Available values ​​are start, center, and end. The default value is center.
snappingDistance	SnappingDistance = "25%"	Snapping activation distance. Can be specified as a percentage of the element size or in absolute values. The default value is 25%.
snappingMethod	SnappingMethod = SnappingMethods.STANDART	Snapping method. Default value is SnappingMethods.STANDART. SnappingMethods.STANDART - Classic group visualization. SnappingMethods.ADVANCED - A mask is applied to the viewport area so that the background is displayed underneath the attached group.
snapScrollToStart	boolean? = true	Determines whether the scroll will be anchored to the start of the list. Default value is "true". This property takes precedence over the snapScrollToEnd property. That is, if snapScrollToStart and snapScrollToEnd are enabled, the list will initially snap to the beginning; if you move the scroll bar to the end, the list will snap to the end. If snapScrollToStart is disabled and snapScrollToEnd is enabled, the list will snap to the end; if you move the scroll bar to the beginning, the list will snap to the beginning. If both snapScrollToStart and snapScrollToEnd are disabled, the list will never snap to the beginning or end. In the spreadingMode=SpreadingModes.INFINITY mode, the snapScrollToStart property is automatically disabled, since the list has no beginning or end.
snapScrollToEnd	boolean? = true	Determines whether the scroll will be anchored to the утв of the list. Default value is "true". That is, if snapScrollToStart and snapScrollToEnd are enabled, the list will initially snap to the beginning; if you move the scroll bar to the end, the list will snap to the end. If snapScrollToStart is disabled and snapScrollToEnd is enabled, the list will snap to the end; if you move the scroll bar to the beginning, the list will snap to the beginning. If both snapScrollToStart and snapScrollToEnd are disabled, the list will never snap to the beginning or end. In the spreadingMode=SpreadingModes.INFINITY mode, the snapScrollToEnd property is automatically disabled, since the list has no beginning or end.
snapToEndTransitionInstantOffset	number? = 0	Sets the offset value; if the scroll area value is exceeded, the scroll animation will be disabled. Default value is "0".
scrollbarEnabled	boolean? = true	Determines whether the scrollbar is shown or not. The default value is "true".
scrollbarInteractive	boolean? = true	Determines whether scrolling using the scrollbar will be possible. The default value is "true".
scrollbarMinSize	number? = 80	Minimum scrollbar size.
scrollbarThickness	number? = 6	Scrollbar thickness.
scrollbarThumbRenderer	TemplateRef | null = null	Scrollbar customization template.
scrollbarThumbParams	{[propName: string]: any;} | null	Additional options for the scrollbar.
scrollBehavior	ScrollBehavior? = 'smooth'	Defines the scrolling behavior for any element on the page. The default value is "smooth".
scrollingSettings	IScrollingSettings = {frictionalForce: 0.035, mass: 0.005, maxDistance: 100000, maxDuration: 4000, speedScale: 10, optimization: true}	Scrolling settings.
scrollingOneByOne	boolean = false	Specifies whether to scroll one item at a time if true and the scrollToItem property is set. The default value is false.
spreadingMode	SpreadingMode ='standart'	The order of list elements. Available values ​​are standard and infinity. normal — list elements are ordered according to the collection sequence. infinity — list elements are ordered cyclically, forming an infinite list. When set to infinity, the alignment property is forced to the value Alignments.CENTER, the scrollbarEnabled property is forced to the false. The default value is standard.
trackBy	string? = 'id'	The name of the property by which tracking is performed.
zIndexWhenSelecting	string | null = null	Defines the zIndex when a list item is selected. The default value is null.

Outputs

Event	Type	Description
onSnapItem	Id	Emit the component ID when an element crosses the alignment line specified by the snapToItemAlign property.
onItemClick	IRenderVirtualListItem | null	Fires when an element is clicked.
onScroll	(IScrollEvent) => void	Fires when the list has been scrolled.
onScrollEnd	(IScrollEvent) => void	Fires when the list has completed scrolling.
onSelect	Array<Id> | Id | null	Fires when an elements are selected.
onCollapse	Array<Id> | Id | null	Fires when elements are collapsed.
onViewportChange	ISize	Fires when the viewport size is changed.
onScrollReachStart	void	Fires when the scroll reaches the start.
onScrollReachEnd	void	Fires when the scroll reaches the end.

Methods

Method	Type	Description
scrollTo	(id: Id, (cb: () => void) | null = null, options: IScrollOptions | null = null)	The method scrolls the list to the element with the given id and returns the value of the scrolled area.
scrollToStart	(cb: (() => void) | null = null, options: IScrollOptions | null = null)	Scrolls the scroll area to the first item in the collection.
scrollToEnd	(cb: (() => void) | null = null, options: IScrollOptions | null = null)	Scrolls the list to the end of the content height.
getItemBounds	(id: Id) => ISize | null	Returns the bounds of an element with a given id
focus	Id, align: FocusAlignment = FocusAlignments.NONE	Focus an list item by a given id.
preventSnapping		Prevents the list from snapping to its start or end edge.

Template API

<ng-template #itemRenderer let-data="data" let-config="config" let-measures="measures" let-api="api">
  <!-- content -->
</ng-template>

Properties

Property	Type	Description
api	NgVirtualListPublicService	List API Provider.
data	{[id: Id ], [otherProps: string]: any;}	Collection item data.
config	IDisplayObjectConfig	Display object configuration. A set of select, collapse, focus and grabbing properties are also provided.
measures	IDisplayObjectMeasures | null	Display object metrics.

VirtualClickModule

Virtual click directive

To correctly handle interactive elements within a list, such as buttons, you need to use the VirtualClick directive.

import { NgVirtualListModule, VirtualClickModule } from 'ng-virtual-list';

@Component({
  selector: 'example',
  imports: [NgVirtualListModule, VirtualClickModule],
})

<ng-template #itemRenderer let-data="data" let-config="config" let-api="api">
  @if (data) {
    <div virtualClick (onVirtualClick)="api.select(data.id, true)">
      <span>{{data.name}}</span>
    </div>
  }
</ng-template>

📦 Previous versions

Angular version	ng-virtual-list version	git	npm
21.x	21.12.4	20.x	21.12.4
20.x	20.12.4	20.x	20.12.4
19.x	19.12.4	19.x	19.12.4
18.x	18.12.4	18.x	18.12.4
17.x	17.12.4	17.x	17.12.4
16.x	16.12.4	16.x	16.12.4
15.x	15.12.4	15.x	15.12.4
14.x	14.12.4	14.x	14.12.4

📄 License

MIT License

Copyright (c) 2026 djonnyx (Evgenii Alexandrovich Grebennikov)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.