Struct VirtualizerOptions 

pub struct VirtualizerOptions<K = ItemKey> {

    pub count: usize,
    pub estimate_size: Arc<dyn Fn(usize) -> u32 + Send + Sync>,
    pub get_item_key: Arc<dyn Fn(usize) -> K + Send + Sync>,
    pub range_extractor: Option<RangeExtractor>,
    pub enabled: bool,
    pub overscan: usize,
    pub initial_rect: Option<Rect>,
    pub padding_start: u32,
    pub padding_end: u32,
    pub scroll_padding_start: u32,
    pub scroll_padding_end: u32,
    pub scroll_margin: u32,
    pub initial_offset: InitialOffset,
    pub on_change: Option<OnChangeCallback<K>>,
    pub use_scrollend_event: bool,
    pub is_scrolling_reset_delay_ms: u64,
    pub should_adjust_scroll_position_on_item_size_change: Option<ShouldAdjustScrollPositionOnItemSizeChangeCallback<K>>,
    pub gap: u32,
}

Configuration for crate::Virtualizer.

This type is designed to be cheap to clone: heavy fields are stored in Arcs so adapters can update a few fields and call Virtualizer::set_options without reallocating closures.

Fields

count: usize

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

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

range_extractor: Option<RangeExtractor>

Optional index selection hook.

When set, the virtualizer will call this extractor to emit the final set of indexes to render. This is useful for pinned/sticky rows, section headers, etc.

The extractor receives the visible range (no overscan) plus overscan and count, and must emit a sorted (ascending) sequence of indexes. Duplicates are allowed but ignored.

enabled: bool

Enables/disables the virtualizer. When disabled, query methods return empty results.

overscan: usize

initial_rect: Option<Rect>

The initial size of the scrollable area (aka TanStack Virtual initialRect).

This is a platform-agnostic rect where:

• main is the virtualized axis size (e.g. height for vertical lists)
• cross is the cross axis size (e.g. width for vertical lists)

padding_start: u32

Padding before the first item.

padding_end: u32

Padding after the last item.

scroll_padding_start: u32

Additional padding applied when computing scroll-to offsets.

scroll_padding_end: u32

Additional padding applied when computing scroll-to offsets.

scroll_margin: u32

Where the list starts inside the scroll element (aka TanStack Virtual scrollMargin).

This is useful when the scroll offset is measured from a larger scroll container (e.g. window scrolling) while the list begins after some header/content.

initial_offset: InitialOffset

Initial scroll offset (aka TanStack Virtual initialOffset).

on_change: Option<OnChangeCallback<K>>

Optional callback fired when the virtualizer’s internal state changes.

The sync argument indicates whether a scroll is in progress.

use_scrollend_event: bool

Determines whether to use a native scrollend event to detect when scrolling has stopped.

This is included for TanStack Virtual parity. In this crate, scrolling state is driven by your adapter via set_is_scrolling/notify_scroll_event/update_scrolling.

is_scrolling_reset_delay_ms: u64

Debounced fallback duration for resetting is_scrolling when use_scrollend_event is false.

should_adjust_scroll_position_on_item_size_change: Option<ShouldAdjustScrollPositionOnItemSizeChangeCallback<K>>

Whether to adjust the scroll position when an item’s measured size differs from its estimate and the item is before the current scroll offset.

gap: u32

Space between items.

Implementations

impl VirtualizerOptions<ItemKey>

pub fn new( count: usize, estimate_size: impl Fn(usize) -> u32 + Send + Sync + 'static, ) -> Self

Creates options for a list keyed by index (ItemKey = u64).

estimate_size(i) should return the estimated item size in the scroll axis (e.g. row height for vertical lists). The estimate is used until an item is measured.

Examples found in repository

examples/basic.rs (line 5)

fn main() {
    let mut v = Virtualizer::new(VirtualizerOptions::new(1_000_000, |_| 1));
    v.set_viewport_and_scroll(10, 123_456);

    let mut items = Vec::new();
    v.for_each_virtual_item(|it| items.push(it));
    println!("total_size={}", v.total_size());
    println!("visible_range={:?}", v.virtual_range());
    println!("first_visible={:?}", items.first());

    let off = v.scroll_to_index_offset(999_999, Align::End);
    v.set_scroll_offset_clamped(off);
    println!("after scroll_to_index: offset={}", v.scroll_offset());
}

examples/keyed_reorder.rs (line 6)

fn main() {
    // Example: measurements follow keys after reorder.
    let mut v = Virtualizer::new(VirtualizerOptions::new(2, |_| 1));
    v.measure(0, 10);
    println!(
        "before reorder: size0={:?} size1={:?}",
        v.item_size(0),
        v.item_size(1)
    );

    // Simulate data reorder by changing the key mapping.
    v.set_get_item_key(|i| if i == 0 { 1 } else { 0 });
    // Note: in real apps you usually keep `get_item_key` stable and call `sync_item_keys()` when
    // your underlying dataset is reordered while `count` stays the same.

    println!(
        "after reorder: size0={:?} size1={:?}",
        v.item_size(0),
        v.item_size(1)
    );
}

examples/measurement_cache.rs (line 9)

fn main() {
    // Example: export and import measurement cache (key -> measured size).
    //
    // This is useful if you want to persist measurements across screens/sessions so that the
    // virtualizer can start with better estimates and avoid re-measuring everything.
    let mut v1 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    v1.measure(2, 10);
    v1.measure(5, 42);

    let snapshot = v1.export_measurement_cache();
    println!("exported_cache_len={}", snapshot.len());

    let mut v2 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    println!(
        "before import: size2={:?} size5={:?}",
        v2.item_size(2),
        v2.item_size(5)
    );

    v2.import_measurement_cache(snapshot);
    println!(
        "after import: cache_len={} size2={:?} size5={:?}",
        v2.measurement_cache_len(),
        v2.item_size(2),
        v2.item_size(5)
    );
}

examples/dynamic_measurement.rs (line 6)

fn main() {
    // Example: dynamic measurement + scroll jump prevention.
    let mut v = Virtualizer::new(VirtualizerOptions::new(100, |_| 10));
    v.set_viewport_and_scroll_clamped(30, 200);

    println!(
        "before: off={} total={} range={:?}",
        v.scroll_offset(),
        v.total_size(),
        v.virtual_range()
    );

    // If an item before the viewport changes size, `resize_item` can adjust scroll_offset to
    // prevent visual jumps.
    let applied = v.resize_item(0, 30);
    println!(
        "resize_item(0): applied_delta={applied} off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // Measuring an item updates sizes and may adjust scroll (TanStack-aligned behavior).
    v.measure(1, 50);
    println!(
        "measure(1): off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // If you want to update measurements without changing scroll, use `measure_unadjusted`.
    v.measure_unadjusted(2, 30);

    // Scroll-to helpers still work with updated measurements.
    let to = v.scroll_to_index_offset(10, Align::Start);
    v.set_scroll_offset_clamped(to);
    println!(
        "set_scroll_offset_clamped(scroll_to_index_offset(10)): off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/tween_scroll.rs (line 49)

fn main() {
    // Simulate an adapter that drives scroll_offset with a tween.
    let mut v = Virtualizer::new(VirtualizerOptions::new(10_000, |_| 1));
    v.set_viewport_and_scroll_clamped(20, 0);

    let to = v.scroll_to_index_offset(2_000, Align::Center);
    let mut tween = Tween::new(v.scroll_offset(), to, 0, 240);

    let mut now_ms = 0u64;
    let mut frame = 0u64;

    loop {
        // Simulate a 60fps "tick".
        now_ms = now_ms.saturating_add(16);
        frame += 1;

        // Adapter samples tween and writes it into the virtualizer.
        let off = tween.sample(now_ms);
        v.apply_scroll_offset_event_clamped(off, now_ms);

        // Render: a UI would iterate items and draw them.
        let mut first: Option<usize> = None;
        let mut last: Option<usize> = None;
        v.for_each_virtual_item(|it| {
            first.get_or_insert(it.index);
            last = Some(it.index);
        });

        if frame.is_multiple_of(5) {
            println!(
                "t={now_ms}ms off={} visible={:?} first={:?} last={:?}",
                v.scroll_offset(),
                v.visible_range(),
                first,
                last
            );
        }

        // Simulate user input interrupting the animation:
        // at ~120ms, retarget to a new index.
        if (120..120 + 16).contains(&now_ms) {
            let new_to = v.scroll_to_index_offset(7_500, Align::Start);
            tween.retarget(now_ms, new_to, 300);
        }

        if tween.is_done(now_ms) {
            break;
        }
    }

    // Mark scroll as finished for adapters that use this state.
    v.set_is_scrolling(false);

    println!(
        "done: off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/pinned_headers.rs (line 8)

fn main() {
    // Example: pinned/sticky "headers" at fixed indexes.
    let mut opts = VirtualizerOptions::new(1_000, |_| 1);
    opts.overscan = 2;

    let pinned: Arc<[usize]> = Arc::from([0usize, 10, 20, 30, 40, 999]);
    opts.range_extractor = Some(Arc::new({
        let pinned = Arc::clone(&pinned);
        move |r: Range, emit: &mut dyn FnMut(usize)| {
            let mut e = IndexEmitter::new(r, emit);
            // IMPORTANT: indexes must be emitted in ascending order.
            //
            // We want pinned rows both before and after the overscanned range. To keep the output
            // sorted, emit:
            // 1) pinned indexes before the overscanned range
            // 2) the overscanned contiguous range
            // 3) pinned indexes after the overscanned range
            let overscanned_start = r.start_index.saturating_sub(r.overscan);
            let overscanned_end = r.end_index.saturating_add(r.overscan).min(r.count);

            for &idx in pinned.iter() {
                if idx < overscanned_start {
                    e.emit_pinned(idx);
                }
            }

            e.emit_overscanned();

            for &idx in pinned.iter() {
                if idx >= overscanned_end {
                    e.emit_pinned(idx);
                }
            }
        }
    }));

    let mut v = Virtualizer::new(opts);
    v.set_viewport_and_scroll_clamped(10, 500);

    let mut collected = Vec::new();
    v.for_each_virtual_index(|i| collected.push(i));

    println!("visible_range={:?}", v.visible_range());
    println!("virtual_range={:?}", v.virtual_range());
    println!(
        "indexes_len={} first_20={:?}",
        collected.len(),
        &collected[..20.min(collected.len())]
    );

    // A real UI would typically iterate items:
    let mut headers = 0usize;
    v.for_each_virtual_item(|it| {
        if pinned.binary_search(&it.index).is_ok() {
            headers += 1;
        }
    });
    println!("pinned_headers_in_output={headers}");
}

Additional examples can be found in:

• examples/adapter_sim.rs

impl<K> VirtualizerOptions<K>

pub fn new_with_key( count: usize, estimate_size: impl Fn(usize) -> u32 + Send + Sync + 'static, get_item_key: impl Fn(usize) -> K + Send + Sync + 'static, ) -> Self

Creates options with a custom key mapping.

Use this when you want measurements to follow items across reordering/replacement: get_item_key(i) should return a stable identity for the item at index i.

pub fn with_get_item_key( self, get_item_key: impl Fn(usize) -> K + Send + Sync + 'static, ) -> Self

pub fn with_range_extractor( self, range_extractor: Option<impl Fn(Range, &mut dyn FnMut(usize)) + Send + Sync + 'static>, ) -> Self

Examples found in repository

examples/adapter_sim.rs (lines 21-26)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn with_enabled(self, enabled: bool) -> Self

pub fn with_initial_rect(self, initial_rect: Option<Rect>) -> Self

Sets the initial viewport rectangle.

Examples found in repository

examples/adapter_sim.rs (lines 12-15)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn with_overscan(self, overscan: usize) -> Self

pub fn with_padding(self, padding_start: u32, padding_end: u32) -> Self

pub fn with_scroll_padding( self, scroll_padding_start: u32, scroll_padding_end: u32, ) -> Self

pub fn with_scroll_margin(self, scroll_margin: u32) -> Self

Examples found in repository

examples/adapter_sim.rs (line 20)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn with_initial_offset(self, initial_offset: InitialOffset) -> Self

pub fn with_initial_offset_value(self, initial_offset: u64) -> Self

pub fn with_initial_offset_provider( self, initial_offset: impl Fn() -> u64 + Send + Sync + 'static, ) -> Self

Examples found in repository

examples/adapter_sim.rs (lines 16-19)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn with_on_change( self, on_change: Option<impl Fn(&Virtualizer<K>, bool) + Send + Sync + 'static>, ) -> Self

pub fn with_use_scrollend_event(self, use_scrollend_event: bool) -> Self

pub fn with_is_scrolling_reset_delay_ms(self, delay_ms: u64) -> Self

pub fn with_should_adjust_scroll_position_on_item_size_change( self, f: Option<impl Fn(&Virtualizer<K>, VirtualItem, i64) -> bool + Send + Sync + 'static>, ) -> Self

pub fn with_gap(self, gap: u32) -> Self

Trait Implementations

impl<K> Clone for VirtualizerOptions<K>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<K> Debug for VirtualizerOptions<K>

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

Formats the value using the given formatter.