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?
answer
- computed, never measured
- count times row height
- top up when the buffer runs low
- worked example: 90px left, four rows
- wrapped lines break the arithmetic
basics
~20 sitemSize 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 linesimport {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
Remember that itemSize is a pixel promise about every row and that the two buffer inputs default to 100 and 200 pixels.
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.
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.
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.