Angular Material CDK Virtual Scrolling: Architecture Decisions for Large Lists

The Problem: DOM Bloat at Scale

Rendering 10,000+ list items in Angular creates a DOM tree that blocks the main thread, drops frames during scroll, and inflates memory. The browser must calculate layout, paint, and composite for every node—even those off-screen. Virtual scrolling solves this by mounting only the visible window plus a small buffer, recycling DOM nodes as the user scrolls.

Takeaway: For fixed-height lists over ~100 items, cdk-virtual-scroll-viewport with a declared itemSize is the smallest viable design. Variable heights require autosize (measurement overhead) or a custom strategy; lists under 100 items rarely justify the complexity.

Requirements

• Render 10k+ items without DOM bloat
• Maintain 60fps scroll by mounting only visible items + buffer (~20-30 nodes)
• Preserve scroll position and accessibility semantics
• Support both finite arrays and infinite-scroll data sources

Smallest Suitable Design

The minimal implementation requires three pieces:

<cdk-virtual-scroll-viewport itemSize="50" class="viewport">
  <ng-template cdkVirtualFor let-item [cdkVirtualForTrackBy]="trackById">
    <app-list-item [data]="item"></app-list-item>
  </ng-template>
</cdk-virtual-scroll-viewport>

CSS (required):

.viewport {
  height: 400px;        /* fixed viewport height */
  width: 100%;
  overflow: auto;       /* viewport must be the scrollable element */
}

Component setup:

@Component({...})
export class ListComponent {
  items = Array.from({length: 10000}, (_, i) => ({id: i, label: `Item ${i}`}));
  trackById = (index: number, item: Item) => item.id;
}

Key constraints:

• itemSize must match the rendered item height in pixels (including margins/padding).
• The viewport element must be the scroll container—do not wrap it in a flex parent with overflow: auto.
• trackBy is mandatory for object arrays; omit only for immutable primitives.

Trust and Data Boundaries

Viewport trusts itemSize

The viewport calculates total scroll range as itemSize * dataSource.length. If actual item height diverges (e.g., itemSize="50" but CSS renders 80px), the scroll thumb misrepresents progress, blank gaps appear, or items clip.

Data source length must be known

For finite lists, the array length drives scroll range. For infinite scroll, you must:

1. Provide a length input on the viewport larger than current data
2. Append data to the source
3. Call viewport.checkViewportSize() after each append

@ViewChild(CdkVirtualScrollViewport) viewport: CdkVirtualScrollViewport;

loadMore() {
  this.items = [...this.items, ...newItems];
  this.viewport.checkViewportSize();
}

Operational Checks

Verify rendered node count

Subscribe to renderedRangeStream in development:

ngAfterViewInit() {
  this.viewport.renderedRangeStream.subscribe(range => {
    console.log('Rendered:', range.start, '-', range.end, 'count:', range.end - range.start);
    // Expect ~20-30 items for 400px viewport @ 50px/item
  });
}

Profile scroll performance

In Chrome DevTools Performance tab, record a scroll gesture. Check for:

• No purple "Layout" or "Recalculate Style" blocks during scroll
• Frame times staying under 16.6ms
• DOM node count stable (Elements panel → search app-list-item)

Assert rendered range matches viewport

// Debug helper
setInterval(() => {
  const range = this.viewport.getRenderedRange();
  const visible = this.viewport.getOffsetToRenderedContentStart();
  console.assert(range.end - range.start < 40, 'Too many nodes rendered');
}, 1000);

Failure Modes

Symptom	Root Cause	Fix
Blank white gaps while scrolling	itemSize smaller than actual item height	Measure rendered item (DevTools Computed tab) and update itemSize
Items overlap or clip	itemSize larger than actual height	Same as above; ensure CSS box-sizing: border-box on items
Scroll position jumps after image load	Dynamic content changes height post-layout	Reserve space with aspect-ratio boxes or use autosize (see design changes)
Flicker or duplicate items on data update	Mutating array without trackBy or ChangeDetectorRef	Always use stable trackBy; prefer immutable updates items = [...items, new]
Scrollbar thumb stuck at top	Viewport not the scroll container (nested overflow)	Move overflow: auto to cdk-virtual-scroll-viewport element

Conditions That Change the Design

Variable item heights → autosize

When items have heterogeneous heights (e.g., user-generated content, wrapped text), replace fixed itemSize with autosize:

<cdk-virtual-scroll-viewport autosize minBufferPx="200" maxBufferPx="400">
  <ng-template cdkVirtualFor let-item [cdkVirtualForTrackBy]="trackById">
    <app-variable-item [data]="item"></app-variable-item>
  </ng-template>
</cdk-virtual-scroll-viewport>

Trade-offs:

• Measures each item on first render via ViewportRuler (layout thrash risk)
• Buffer tuning (minBufferPx/maxBufferPx) affects memory vs. scroll smoothness
• Not suitable for rapidly changing heights (animations, collapsing sections)

Extremely heterogeneous lists → Custom VirtualScrollStrategy

If autosize measurement cost is prohibitive (e.g., 50k items with complex layouts), implement a strategy that estimates heights from metadata:

class EstimatedStrategy extends VirtualScrollStrategy {
  constructor(private estimates: Map) { super(); }
  // Implement scrolledIndexChange, updateViewport, etc.
}

Small lists (<100 items) → Remove virtual scrolling

Below ~100 items, the overhead of virtual scroll (measurement, buffer management, strategy indirection) exceeds the cost of rendering all nodes. Use a plain *ngFor with trackBy.

Verification Checklist

1. Create test component with 10,000 fixed-height items; confirm DOM nodes stay <50 during scroll
2. Log scrolledIndexChange events; verify smooth incremental updates
3. Introduce deliberate itemSize mismatch (50px vs 80px actual); observe blank areas
4. Run Lighthouse Performance audit; ensure no forced synchronous layouts on scroll
5. Test infinite scroll: append 100 items, call checkViewportSize(), verify no scroll jump

Limitations

• autosize measures synchronously on first render—can cause jank on low-end devices with complex items
• No built-in support for variable-height items with dynamic content (images, async data) without manual height reservation
• Keyboard navigation (Home/End/PageUp) requires custom handling for accessibility compliance
• Server-side rendering: viewport dimensions unknown at build time; requires ViewportRuler polyfill or client-only hydration

When to Revisit

Re-evaluate the design if:

• Item height variance exceeds 3x (consider custom strategy)
• Scroll jank appears on 4-year-old mobile hardware (profile first)
• List size drops below 100 items consistently (remove virtual scroll)
• Accessibility audit fails on scroll position announcement (add ARIA live regions)