skip to content

In the Angular CDK's fixed-size virtual scroll strategy, what do itemSize, minBufferPx and maxBufferPx control, and what breaks when rows aren't itemSize tall?

level: middleimportance: must knowfreq 36%

answer

  1. computed, never measured
  2. count times row height
  3. top up when the buffer runs low
  4. worked example: 90px left, four rows
  5. wrapped lines break the arithmetic

basics

~20 s

itemSize is the pixel height assumed for every row and drives total height, visible index and offsets; minBufferPx is the least off-screen buffer allowed, maxBufferPx the level refilled to. Rows of another height make content jump.

solid answer

~40 s

`itemSize` on `<cdk-virtual-scroll-viewport>` attaches the fixed-size strategy, which never measures rows: total height is count × `itemSize`, the first visible index is scroll offset ÷ `itemSize`, and the rendered block is placed at start × `itemSize`. `minBufferPx` (default 100) is the least off-screen content allowed before more rows render; `maxBufferPx` (default 200) is how much to render back up to, so with `itemSize` 50 and a 250 maximum, a buffer that drops to 90px gets four more rows. If `maxBufferPx` is below `minBufferPx`, development mode throws. Rows that aren't really `itemSize` tall break every one of those formulas: content jumps as the range shifts, blank bands or overshoot appear, and `scrollToIndex` misses its line — so pin row height in CSS, in px.

code

ts · 28 lines
ts
import {Component, input} from '@angular/core';
import {ScrollingModule} from '@angular/cdk/scrolling';

export interface AuditLine {
  id: number;
  timestamp: string;
  actor: string;
  action: string;
}

@Component({
  selector: 'app-audit-log',
  imports: [ScrollingModule],
  template: `
    <cdk-virtual-scroll-viewport itemSize="32" minBufferPx="320" maxBufferPx="640" class="log">
      <div class="line" *cdkVirtualFor="let line of lines()">
        {{ line.timestamp }} {{ line.actor }} {{ line.action }}
      </div>
    </cdk-virtual-scroll-viewport>
  `,
  styles: `
    .log { height: 480px; }
    .line { height: 32px; box-sizing: border-box; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
  `,
})
export class AuditLog {
  readonly lines = input.required<AuditLine[]>();
}

go deeper

for a junior

Remember that itemSize is a pixel promise about every row and that the two buffer inputs default to 100 and 200 pixels.

for a middle

Walk through the formulas the strategy uses, and work the buffer example aloud: a 90px buffer against a 250px maximum with 50px rows renders four more rows.

for a senior

Diagnose the symptoms of a broken row-height contract — jumping, blank bands, a lying index readout — and fix them in CSS with px heights and truncation rather than by tuning buffers.

for a principal

Decide where uniform rows are an acceptable product constraint for the speed they buy, and where uneven content justifies a costlier strategy or a different design.

## The fixed-size strategy in one sentence Adding `itemSize` to `<cdk-virtual-scroll-viewport>` attaches the `CdkFixedSizeVirtualScroll` directive (selector `cdk-virtual-scroll-viewport[itemSize]`), which creates a `FixedSizeVirtualScrollStrategy` and provides it through the `VIRTUAL_SCROLL_STRATEGY` token. That strategy **never measures a row**. Every number it produces is arithmetic on three inputs, which is why it is fast and why it is strict. ## The three inputs | Input | Unit | Default in source | What it drives | |---|---|---|---| | `itemSize` | px | 20 | total size = count × `itemSize`; first visible index = offset ÷ `itemSize`; wrapper offset = range start × `itemSize`; `scrollToIndex(i)` target = i × `itemSize` | | `minBufferPx` | px | 100 | the least buffer allowed beyond the visible area before more rows render | | `maxBufferPx` | px | 200 | how much buffer to render back up to when it runs low | In practice you always write `itemSize` yourself, because the directive only exists where the attribute is present; the buffer defaults are the ones you actually inherit. ## How the two buffers interact The CDK guide's worked example: 1. Configuration: `itemSize = 50`, `minBufferPx = 100`, `maxBufferPx = 250`. 2. While the user scrolls down, the content rendered below the visible area shrinks to **90px** — under `minBufferPx`. 3. The strategy renders enough rows to get back to `maxBufferPx`: (250 − 90) ÷ 50 = 3.2, rounded up to **4 rows**, 200px. 4. The buffer is now **290px**, above `maxBufferPx`, and nothing more renders until it falls below 100px again. Read the pair as two dials: - **`minBufferPx`** sets how far ahead of the user rows already exist. Raising it reduces the blank flash on a fast fling at the cost of more rows in the DOM. - **The gap up to `maxBufferPx`** sets the batch size. A wider gap means fewer, larger render passes; a narrow one means frequent small ones. - **Consistency is enforced.** If `maxBufferPx` is smaller than `minBufferPx`, the directive throws in development mode: "maxBufferPx must be greater than or equal to minBufferPx". For the audit log, 32px rows in a 480px viewport with `minBufferPx="320"` and `maxBufferPx="640"` aim to keep at least ten lines ready beyond the visible area and top up roughly ten at a time. ## Setting it up so the arithmetic holds - Import `ScrollingModule` from `@angular/cdk/scrolling` (or the standalone `CdkVirtualScrollViewport`, `CdkFixedSizeVirtualScroll` and `CdkVirtualForOf`) into the component's `imports`. - Give the viewport a height; it is a strictly contained scroll box and collapses without one. - Give every row a CSS `height` equal to `itemSize`, with `box-sizing: border-box` so borders and padding count inside it, and no vertical margins between rows — margins add to the real pitch. - Truncate long lines (`white-space: nowrap`, `text-overflow: ellipsis`) instead of letting them wrap; offer the full text elsewhere, such as a detail panel. ## What breaks when rows are not `itemSize` tall Because positions are computed, a mismatch shows up as visible defects rather than as an error: - **Taller rows** — say a wrapped audit line at 48px under `itemSize="32"`. The rendered block is longer than the strategy believes, so every time the range shifts and the wrapper is re-placed at start × 32, the content visibly **jumps**, and the scrollbar no longer matches the content. - **Shorter rows** — the strategy renders fewer pixels than it thinks, so a **blank band** can open at the bottom of the viewport, and the oversized spacer lets the user scroll past the last line into empty space. - **Index APIs drift** — `scrollToIndex` lands near the requested line but not on it, and `scrolledIndexChange` reports the wrong first line, so a "line N of M" readout lies. - **Relative units** — a row styled `2rem` is 32px only at a 16px root font size; a user who enlarges the browser's default font gets taller rows than `itemSize="32"`. Size rows in px, or compute `itemSize` from the real row height at runtime. It is an ordinary input: changing it pushes all three values into the strategy, which recomputes the total size and the rendered range. When rows genuinely differ in height, such as a message thread, the fixed-size strategy is the wrong tool; the experimental autosize strategy or a custom `VirtualScrollStrategy` is the route. ## Tables Since Angular CDK 21.1, a Material or CDK table can be virtualized directly by placing it inside a `<cdk-virtual-scroll-viewport itemSize="…">` in the same template. The same contract applies: every data row must be `itemSize` tall, and the table switches on fixed layout so columns do not jump as rows are swapped.

  • How do you virtualize an Angular Material table of audit entries?
    Since Angular CDK 21.1 the table supports it directly: put the Material table inside `<cdk-virtual-scroll-viewport itemSize="…">` in the same template and give the viewport a height. The table picks up the viewport and renders only the range it computes. Fixed table layout is always on so columns don't jump, and row templates that use a `when` predicate are rejected in development mode.
  • Can itemSize change while the list is on screen?
    Yes. `itemSize`, `minBufferPx` and `maxBufferPx` are ordinary inputs; when one changes, the directive passes all three to the strategy, which recomputes the total size and the rendered range. A compact/comfortable toggle can bind `[itemSize]` to a signal, provided the row CSS changes height in the same render — otherwise rows and positions disagree until it does.
  • Why not simply set huge buffers so the user never sees a blank flash?
    Every buffer pixel is rendered rows: a 5,000px buffer at 32px rows keeps about 150 extra lines on each side in the DOM, which brings back the layout and change-detection cost virtual scrolling exists to remove. Size `minBufferPx` to cover about one fast flick, and the gap to `maxBufferPx` to batch renders.

  • The fixed-size strategy measures each row and corrects its offsets after rendering.
  • itemSize only sets how many rows render initially; real row heights take over afterwards.
  • maxBufferPx is a hint, so setting it below minBufferPx is harmless.
  • The bigger the buffers, the better virtual scrolling performs.
  • A rem-based row height is safe because itemSize is also interpreted in rem.
  • The viewport clips each row to itemSize, so wrapped text cannot break the layout.

Assumes Angular CDK 22; Material and CDK tables accept a wrapping virtual scroll viewport since 21.1, and the itemSize and buffer inputs are unchanged across recent majors.