How to Use Angular CDK Virtual Scroll for Efficient Lists

Use Angular CDK virtual scroll by importing ScrollingModule and wrapping your list in a cdk-virtual-scroll-viewport component. Bind your data array to an *cdkVirtualFor directive inside the viewport to render only visible items, improving performance for large lists.

Syntax

The main parts of Angular CDK virtual scroll are:

• cdk-virtual-scroll-viewport: A container that manages the visible area and scrolling.
• *cdkVirtualFor: A directive similar to *ngFor that renders only visible items.
• itemSize: An input specifying the height (in pixels) of each item for proper virtualization.

html

<cdk-virtual-scroll-viewport itemSize="50" class="viewport">
  <div *cdkVirtualFor="let item of items" class="item">
    {{item}}
  </div>
</cdk-virtual-scroll-viewport>

Output

A scrollable list showing only visible items, each 50px tall, improving performance.

Example

This example shows a simple Angular component using CDK virtual scroll to display 1000 items efficiently.

typescript

import { Component } from '@angular/core';

@Component({
  selector: 'app-virtual-scroll',
  template: `
    <cdk-virtual-scroll-viewport itemSize="40" class="viewport">
      <div *cdkVirtualFor="let item of items" class="item">
        {{item}}
      </div>
    </cdk-virtual-scroll-viewport>
  `,
  styles: [
    `.viewport { height: 200px; width: 300px; border: 1px solid #ccc; }
     .item { height: 40px; display: flex; align-items: center; padding-left: 10px; border-bottom: 1px solid #eee; }`
  ]
})
export class VirtualScrollComponent {
  items = Array.from({ length: 1000 }).map((_, i) => `Item #${i + 1}`);
}

Output

A scrollable box 200px tall showing a smooth list of items from 'Item #1' to 'Item #1000', rendering only visible items for performance.

Common Pitfalls

Common mistakes when using Angular CDK virtual scroll include:

• Not setting itemSize correctly, causing layout issues.
• Using variable height items without special handling, which CDK virtual scroll does not support by default.
• Forgetting to import ScrollingModule in your Angular module.
• Trying to use *ngFor inside the viewport instead of *cdkVirtualFor.

html

/* Wrong: Using *ngFor inside viewport */
<cdk-virtual-scroll-viewport itemSize="50">
  <div *ngFor="let item of items"> {{item}} </div>
</cdk-virtual-scroll-viewport>

/* Right: Use *cdkVirtualFor */
<cdk-virtual-scroll-viewport itemSize="50">
  <div *cdkVirtualFor="let item of items"> {{item}} </div>
</cdk-virtual-scroll-viewport>

Quick Reference

Property/Directive	Description
cdk-virtual-scroll-viewport	Container that enables virtual scrolling.
*cdkVirtualFor	Directive to loop over items with virtualization.
itemSize	Height in pixels of each item (required).
minBufferPx	Optional: Minimum buffer pixels before loading more items.
maxBufferPx	Optional: Maximum buffer pixels to keep rendered.
ScrollingModule	Angular module to import for virtual scroll.

Key Takeaways

Import ScrollingModule and use cdk-virtual-scroll-viewport to enable virtual scrolling.

Use *cdkVirtualFor instead of *ngFor inside the viewport to render only visible items.

Set itemSize correctly to match your item height for proper scrolling behavior.

Angular CDK virtual scroll improves performance by rendering only visible list items.

Avoid variable height items unless using advanced strategies or custom solutions.