Error: cdk-virtual-scroll-viewport requires the "itemSize" p

Error message

Error: cdk-virtual-scroll-viewport requires the "itemSize" property to be set.

What it means

The cdk-virtual-scroll-viewport needs a scroll strategy to know item sizes; by default this comes from the required itemSize input. If no strategy has been configured and itemSize was not set, the constructor throws so the viewport fails fast instead of rendering nothing.

Source

Thrown at src/cdk/scrolling/virtual-scroll-viewport.ts:206

  private _changeDetectionNeeded = signal(false);

  /** A list of functions to run after the next change detection cycle. */
  private _runAfterChangeDetection: Function[] = [];

  /** Subscription to changes in the viewport size. */
  private _viewportChanges = Subscription.EMPTY;

  private _injector = inject(Injector);

  private _isDestroyed = false;

  constructor() {
    super();
    const viewportRuler = inject(ViewportRuler);

    if (!this._scrollStrategy && (typeof ngDevMode === 'undefined' || ngDevMode)) {
      throw Error('Error: cdk-virtual-scroll-viewport requires the "itemSize" property to be set.');
    }

    this._viewportChanges = viewportRuler.change().subscribe(() => {
      this.checkViewportSize();
    });

    if (!this.scrollable) {
      // No scrollable is provided, so the virtual-scroll-viewport needs to become a scrollable
      this.elementRef.nativeElement.classList.add('cdk-virtual-scrollable');
      this.scrollable = this;
    }

    const ref = effect(
      () => {
        if (this._changeDetectionNeeded()) {
          this._doChangeDetection();
        }
      },

View on GitHub (pinned to 0411926e7d)

Solutions

Add the [itemSize] input to cdk-virtual-scroll-viewport (e.g. [itemSize]="50" for 50px rows)
If item sizes vary, provide a custom strategy: { provide: CDK_VIRTUAL_SCROLL_STRATEGY, useClass: CustomVirtualScrollStrategy } in the viewport or component providers
Check for casing typos in the binding so Angular actually picks it up
If using fixed-size strategy via providedIn, verify it is registered on the viewport element

Example fix

<!-- before -->
<cdk-virtual-scroll-viewport class="list">
  <div *cdkVirtualFor="let item of items">{{item}}</div>
</cdk-virtual-scroll-viewport>
<!-- after -->
<cdk-virtual-scroll-viewport class="list" [itemSize]="48">
  <div *cdkVirtualFor="let item of items">{{item}}</div>
</cdk-virtual-scroll-viewport>

Defensive patterns

Strategy: validation

Validate before calling

@Component({
  template: `<cdk-virtual-scroll-viewport [itemSize]="itemSize" ...>`,
})
class ListComponent {
  itemSize = input.required<number>(); // fail fast if the size is not provided
}

Type guard

function hasScrollStrategyConfig(opts: { itemSize?: number; strategy?: VirtualScrollStrategy }): boolean {
  return opts.itemSize != null || opts.strategy != null;
}

Try / catch

try {
  this.viewport && this.viewport.checkViewportSize();
} catch (e) {
  if (e instanceof Error && e.message.includes('itemSize')) {
    console.error('cdk-virtual-scroll-viewport is missing the [itemSize] input or a CDK_VIRTUAL_SCROLL_STRATEGY provider.');
  } else {
    throw e;
  }
}

Prevention

Always set [itemSize] on cdk-virtual-scroll-viewport when using fixed-size scrolling
For variable item sizes, provide CDK_VIRTUAL_SCROLL_STRATEGY with a custom strategy class
Watch for binding typos ([itemsize]) that Angular silently ignores
Write a template type-check/test that asserts required inputs are present

When it happens

Trigger: Using <cdk-virtual-scroll-viewport> without an [itemSize] binding and without providing a custom scroll strategy via CDK_VIRTUAL_SCROLL_STRATEGY; forgetting the itemSize binding after refactoring to a custom strategy that was never injected.

Common situations: Copy-pasting the viewport element but dropping the [itemSize] attribute; dynamic item sizes handled by removing itemSize without supplying a CustomVirtualScrollStrategy provider; typos like [itemsize] that Angular ignores.

Related errors

AI-assisted analysis of angular/components@0411926e7d (2026-08-31). Data as JSON: /api/errors/89ae67ad0b90be06. Report an issue: GitHub.