Struct LazyListState 

pub struct LazyListState { /* private fields */ }

Re-export the UI crate so applications can depend on a single crate. 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 pointer to the inner state for unique identification. Used by scroll gesture detection to create unique keys.

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 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 scroll direction for prefetch calculations. Positive = scrolling forward (content moving up), negative = backward.

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, callback: Rc<dyn Fn()>) -> bool

Tries to register a layout invalidation callback.

Returns true if the callback was registered, false if one was already registered. This prevents duplicate registrations on recomposition.

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