Struct VirtualizerOptions 

pub struct VirtualizerOptions {

    pub item_count: usize,
    pub item_size_mode: ItemSizeMode,
    pub scroll_direction: ScrollDirection,
    pub overscan: usize,
    pub padding_start: f64,
    pub padding_end: f64,
    pub scroll_padding_start: f64,
    pub scroll_padding_end: f64,
    pub gap: f64,
    pub lanes: usize,
    pub scroll_margin: f64,
    pub container_size: Option<f64>,
    pub use_window_scroll: bool,
    pub initial_offset: f64,
    pub initial_rect: Rect,
    pub enabled: bool,
    pub is_rtl: bool,
    pub index_attribute: String,
    pub is_scrolling_reset_delay: u32,
    pub use_scrollend_event: bool,
    pub use_animation_frame_with_resize_observer: bool,
    pub estimate_size: Option<Arc<dyn Fn(usize) -> f64 + Send + Sync>>,
    pub get_item_key: Option<Arc<dyn Fn(usize) -> VirtualKey + Send + Sync>>,
    pub range_extractor: Option<Arc<dyn Fn(VisibleRange) -> Vec<usize> + Send + Sync>>,
    pub initial_measurements_cache: Vec<VirtualItem>,
    pub initial_offset_fn: Option<Arc<dyn Fn() -> f64 + Send + Sync>>,
    pub on_change: Option<Arc<dyn Fn() + Send + Sync>>,
    pub scroll_to_fn: Option<Arc<dyn Fn(f64, ScrollToOptions) + Send + Sync>>,
    pub should_adjust_scroll_position_on_item_size_change: Option<ShouldAdjustScrollOnResizeFn>,
    pub adjust_scroll_on_resize_during_smooth_scroll: bool,
    pub measure_element: Option<MeasureElementFn>,
    pub measure_during_scroll: bool,
    pub scroll_reconciliation_timeout_ms: u32,
    pub scroll_reconciliation_stable_frames: u32,
}

Configuration options for initializing a virtualizer instance.

Contains all parameters the virtualizer needs to compute visible ranges, item positions, and total scrollable size. Developers configure these options before creating a virtualizer.

Fields

item_count: usize

Total number of items in the dataset.

item_size_mode: ItemSizeMode

Strategy for determining item sizes.

scroll_direction: ScrollDirection

Scroll direction (vertical or horizontal).

overscan: usize

Number of extra items to render beyond the visible viewport.

padding_start: f64

Padding in pixels before the first item.

padding_end: f64

Padding in pixels after the last item.

scroll_padding_start: f64

Extra scroll padding at the start that affects scroll-to alignment calculations but does not affect total size.

scroll_padding_end: f64

Extra scroll padding at the end that affects scroll-to alignment calculations but does not affect total size.

gap: f64

Gap in pixels between consecutive items.

lanes: usize

Number of parallel lanes (columns for vertical, rows for horizontal).

When greater than 1, items are distributed across lanes using a shortest-lane-first algorithm. Enables grid-style layouts.

scroll_margin: f64

Offset applied to item positions to account for elements above the virtualizer (e.g., sticky headers). Affects total size and measurement start offsets.

container_size: Option<f64>

Optional fixed size of the scroll container viewport in pixels.

When None, the container size must be provided via measurement or set dynamically at runtime.

use_window_scroll: bool

Whether to use window-level scrolling instead of a scroll container.

initial_offset: f64

Initial scroll offset in pixels. Applied when the virtualizer is first created to restore scroll position.

initial_rect: Rect

Initial scroll container dimensions before measurement is available.

enabled: bool

Whether the virtualizer is enabled. When disabled, clears all measurements and returns empty items without destroying the instance.

is_rtl: bool

Whether the scroll container uses right-to-left direction. Inverts horizontal scroll offset when true.

index_attribute: String

DOM attribute name used to look up item indices on measured elements. Defaults to "data-index".

is_scrolling_reset_delay: u32

Delay in milliseconds before is_scrolling resets to false after scrolling stops. Defaults to 150.

use_scrollend_event: bool

Whether to use the native scrollend event instead of debounce for detecting scroll stop.

use_animation_frame_with_resize_observer: bool

Whether to wrap ResizeObserver callbacks in requestAnimationFrame to avoid layout thrashing.

estimate_size: Option<Arc<dyn Fn(usize) -> f64 + Send + Sync>>

Per-index size estimation callback. When provided, overrides the scalar value from item_size_mode for initial estimates. Each call receives an item index and returns the estimated size.

get_item_key: Option<Arc<dyn Fn(usize) -> VirtualKey + Send + Sync>>

Custom key extractor callback. When provided, returns a stable identity key for each item index. Defaults to using the index.

range_extractor: Option<Arc<dyn Fn(VisibleRange) -> Vec<usize> + Send + Sync>>

Custom range extractor callback. When provided, returns the list of item indices to render given the visible range. Enables sticky headers, pinned rows, and other custom layouts.

initial_measurements_cache: Vec<VirtualItem>

Pre-populated measurements cache for SSR hydration or state restoration. When provided, these cached items are used instead of estimates on the first measurement pass.

initial_offset_fn: Option<Arc<dyn Fn() -> f64 + Send + Sync>>

When set, overrides initial_offset on construction with the callback result.

on_change: Option<Arc<dyn Fn() + Send + Sync>>

Invoked when range, scroll state, or layout affecting visible items changes.

Framework hooks use this to schedule renders without polling.

scroll_to_fn: Option<Arc<dyn Fn(f64, ScrollToOptions) + Send + Sync>>

Custom programmatic scroll implementation. When None, hooks use the browser default (scrollTo on the container or window).

Receives the logical scroll offset and full scroll options.

should_adjust_scroll_position_on_item_size_change: Option<ShouldAdjustScrollOnResizeFn>

When set, decides whether to adjust scroll when an item above the viewport resizes. Arguments are (index, previous_size, new_size).

adjust_scroll_on_resize_during_smooth_scroll: bool

When false, scroll compensation for resizes above the viewport is skipped while a smooth programmatic scroll is active.

measure_element: Option<MeasureElementFn>

Custom measurement from observed element size. Arguments are (border_width, border_height, scroll_direction); return size along the scroll axis.

measure_during_scroll: bool

When false, hooks may skip attaching ResizeObserver work during active scroll.

scroll_reconciliation_timeout_ms: u32

Maximum duration in milliseconds for smooth-scroll reconciliation.

scroll_reconciliation_stable_frames: u32

Consecutive matching frames required before smooth scroll is considered settled.

Trait Implementations

impl Clone for VirtualizerOptions

fn clone(&self) -> VirtualizerOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VirtualizerOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the options for debug output, omitting closure fields.

impl Default for VirtualizerOptions

fn default() -> Self

Returns sensible default virtualizer options.

Returns

• VirtualizerOptions: Defaults with zero items, fixed 50px size, vertical direction, overscan of 5, and no padding or gap.

impl PartialEq for VirtualizerOptions

fn eq(&self, other: &Self) -> bool

Compares options for equality, ignoring closure fields.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.