interface@af-utils/virtual-core
On this page

VirtualScrollerRuntimeParams

VirtualScroller parameters that may change over time. Used as VirtualScroller.set argument type.

Remarks

Implemented as interface for better documentation output (api-extractor)

Extended by

Properties

estimatedItemSize?

optional estimatedItemSize?: number;

Estimated height/width of scrollable item. Orientation is determined by VirtualScrollerInitialParams.horizontal.

Remarks

Actual size is always reported by internal ResizeObserver when VirtualScroller.attachItem is called. Bad item size assumptions can turn into shaky scrolling experience. Accuracy here is rewarded.

Assigning a different estimatedItemSize through VirtualScroller.set preserves cached sizes in the currently rendered [from, to) range and resets cached sizes outside it to the new estimate. Consequently, an item in that range which is still awaiting its first ResizeObserver delivery can temporarily retain the previous estimate. When scrolling is idle, the model corrects the native offset to preserve the current visible anchor; an end-aligned viewport remains at the end.

itemCount?

optional itemCount?: number;

Total items quantity

Remarks

Maximum supported value is 4_194_303 (2^22 - 1). The dense size and Fenwick stores use roughly 16 bytes per item, so the maximum consumes about 64 MiB before ordinary object and DOM overhead. The bound also keeps bitwise Fenwick traversal inside the positive signed 32-bit range. But there is one more limit. W3C does not provide maximum allowed values for height, width, margin, etc.

CSS theoretically supports infinite precision and infinite ranges for all value types; however in reality implementations have finite capacity. UAs should support reasonably useful ranges and precisions

This quote was found here. Chrome’s experimentally found maximum value is 33_554_428. So some problems may happen if VirtualScroller.scrollSize is bigger.

overscanCount?

optional overscanCount?: number;

Amount of items rendered before or after visible ones.

Remarks

Render place depends on scroll direction:

  • if scrolling is done forward - these items are rendered after visible ones;

  • If backward - before.

Changing only overscanCount does not invalidate the currently published range. The new value is applied by the next natural range recalculation.