Struct LazyListState 

pub struct LazyListState { /* private fields */ }

State object for lazy list scroll position tracking.

Holds the current scroll position and provides methods to programmatically control scrolling. Create with remember_lazy_list_state() in composition.

This type is Copy, so it can be passed to multiple closures without explicit .clone() calls.

Reactive Properties (read during composition triggers recomposition)

• first_visible_item_index() - index of first visible item
• first_visible_item_scroll_offset() - scroll offset within first item
• can_scroll_forward() - whether more items exist below/right
• can_scroll_backward() - whether more items exist above/left
• stats() - lifecycle statistics (items_in_use, items_in_pool)

Non-Reactive Properties

• stats().total_composed - total items composed (diagnostic)
• stats().reuse_count - items reused from pool (diagnostic)
• layout_info() - detailed layout information

Example

let state = remember_lazy_list_state();

// Scroll to item 50
state.scroll_to_item(50, 0.0);

// Get current visible item (reactive read)
println!("First visible: {}", state.first_visible_item_index());

Implementations

impl LazyListState

pub fn inner_ptr(&self) -> *const ()

Returns a stable identity pointer for the live inner state allocation.

The pointer comes from the Rc stored inside inner, so it remains stable for the lifetime of a live LazyListState and can be used as a composition identity key.

pub fn first_visible_item_index(&self) -> usize

Returns the index of the first visible item.

When called during composition, this creates a reactive subscription so that changes to the index will trigger recomposition.

pub fn first_visible_item_scroll_offset(&self) -> f32

Returns the scroll offset of the first visible item.

This is the amount the first item is scrolled off-screen (positive = scrolled up/left). When called during composition, this creates a reactive subscription so that changes to the offset will trigger recomposition.

pub fn is_scrolled_non_reactive(&self) -> bool

Returns whether the list is positioned away from its origin without creating a reactive subscription.

pub fn layout_info(&self) -> LazyListLayoutInfo

Returns the layout info from the last measure pass.

pub fn stats(&self) -> LazyLayoutStats

Returns the current item lifecycle statistics.

When called during composition, this creates a reactive subscription so that changes to items_in_use or items_in_pool will trigger recomposition. The total_composed and reuse_count fields are diagnostic and non-reactive.

pub fn update_stats(&self, items_in_use: usize, items_in_pool: usize)

Updates the item lifecycle statistics.

Called by the layout measurement after updating slot pools. Triggers recomposition if items_in_use or items_in_pool changed.

pub fn record_composition(&self, was_reused: bool)

Records that an item was composed (either new or reused).

This updates diagnostic counters in non-reactive state. Does NOT trigger recomposition.

pub fn record_scroll_direction(&self, delta: f32)

Records the raw scroll delta for prefetch calculations.

Cranpose lazy lists use gesture-style deltas:

• Negative delta = scrolling forward (content moves up)
• Positive delta = scrolling backward (content moves down)

pub fn update_prefetch_queue( &self, first_visible_index: usize, last_visible_index: usize, total_items: usize, )

Updates the prefetch queue based on current visible items. Should be called after measurement to queue items for pre-composition.

pub fn take_prefetch_indices(&self) -> Vec<usize>

Returns the indices that should be prefetched. Consumes the prefetch queue.

pub fn scroll_to_item(&self, index: usize, scroll_offset: f32)

Scrolls to the specified item index.

Arguments

• index - The index of the item to scroll to
• scroll_offset - Additional offset within the item (default 0)

pub fn dispatch_scroll_delta(&self, delta: f32) -> f32

Dispatches a raw scroll delta.

Returns the amount of scroll actually consumed.

This triggers layout invalidation via registered callbacks. The callbacks are registered by LazyColumnImpl/LazyRowImpl with schedule_layout_repass(node_id), which provides O(subtree) performance instead of O(entire app).

pub fn peek_scroll_delta(&self) -> f32

Peeks at the pending scroll delta without consuming it.

Used for direction inference before measurement consumes the delta. This is more accurate than comparing first visible index, especially for:

• Scrolling within the same item (partial scroll)
• Variable height items where scroll offset changes without index change

pub fn cache_item_size(&self, index: usize, size: f32)

Caches the measured size of an item for scroll estimation.

Uses a HashMap + VecDeque LRU pattern with O(1) insertion and eviction. Re-measurement of existing items (uncommon during normal scrolling) requires O(n) VecDeque position lookup, but the cache is small (100 items).

Performance Note

If profiling shows this as a bottleneck, consider using the lru crate for O(1) update-in-place operations, or a linked hash map.

pub fn get_cached_size(&self, index: usize) -> Option<f32>

Gets a cached item size if available.

pub fn average_item_size(&self) -> f32

Returns the running average of measured item sizes.

pub fn nearest_range(&self) -> Range<usize>

Returns the current nearest range for optimized key lookup.

pub fn update_scroll_position_if_item_moved<F>( &self, new_item_count: usize, get_index_by_key: F, ) -> usize

where F: Fn(u64) -> Option<usize>,

Adjusts scroll position if the first visible item was moved due to data changes.

Matches JC’s updateScrollPositionIfTheFirstItemWasMoved. If items were inserted/removed before the current scroll position, this finds the item by its key and updates the index accordingly.

Returns the adjusted first visible item index.

pub fn can_scroll_forward(&self) -> bool

Returns whether we can scroll forward (more items below/right).

When called during composition, this creates a reactive subscription so that changes will trigger recomposition.

pub fn can_scroll_backward(&self) -> bool

Returns whether we can scroll backward (more items above/left).

When called during composition, this creates a reactive subscription so that changes will trigger recomposition.

pub fn add_invalidate_callback(&self, callback: Rc<dyn Fn()>) -> u64

Adds an invalidation callback.

pub fn try_register_layout_callback( &self, node_id: usize, callback: Rc<dyn Fn()>, ) -> Option<u64>

Tries to register a layout invalidation callback for the specified node.

Returns the callback id for the active layout callback.

Registering again always replaces the previous active layout callback, even when the node id stays the same. This keeps ownership tied to the latest effect instance so disposing an older scope cannot unregister the live callback.

pub fn remove_invalidate_callback(&self, id: u64)

Removes an invalidation callback.

Trait Implementations

impl Clone for LazyListState

fn clone(&self) -> LazyListState

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl PartialEq for LazyListState

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl Copy for LazyListState