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

VirtualScrollerInitialParams

All VirtualScroller parameters (that may / may not change over time).

Remarks

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

Extends

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.

Inherited from

VirtualScrollerRuntimeParams.estimatedItemSize

estimatedScrollElementOffset?

optional estimatedScrollElementOffset?: number;

Estimated distance between top/left edges of scrollable container and first scrollable item.

Remarks

Does not equal 0 only when scrollable container and items container are different elements. VirtualScroller.setContainer has more explanation.

estimatedWidgetSize?

optional estimatedWidgetSize?: number;

Estimated size of scroll element.

Remarks

Actual size is always reported by ResizeObserver, but this property together with VirtualScrollerRuntimeParams.estimatedItemSize and VirtualScrollerRuntimeParams.overscanCount can be used in server-side rendering.

Quantity of SSR-rendered elements can be calculated this way:

Math.min( itemCount, Math.ceil( estimatedWidgetSize / estimatedItemSize ) + overscanCount )

horizontal?

optional horizontal?: boolean;

Scroll container orientation.

Remarks

Determines properties used for dimension/scroll calculations, for example:

  • scrollTop / scrollLeft;

  • height / width;

  • innerHeight / innerWidth.

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.

Inherited from

VirtualScrollerRuntimeParams.itemCount

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.

Inherited from

VirtualScrollerRuntimeParams.overscanCount