VirtualList

VirtualList accepts a range and item factory, a State<Range>, or an item count and index factory.

Declare lazy items

VirtualList(items, [](const Item& item) {
  return ItemRow(item).Key(item.id);
})
    .EstimatedItemExtent(56.0F)
    .CacheExtent(240.0F)

Items are materialized on demand for the viewport plus cache extent. The factory must return a View; use stable keys for items whose state must follow semantic identity.

Tune extent and cache

.ItemExtent(...) enables fixed-extent positioning. Use .EstimatedItemExtent(...) for variable-height items so initial range and scroll corrections start from a useful estimate. .CacheExtent(...) keeps nearby content realized to reduce visible creation during scrolling.

Control axis and position

.ScrollAxis(Axis::Horizontal) changes the main axis. .Controller(...) connects a ScrollController, including ScrollToItem(index, alignment).

VirtualList emits collection and realized item semantics without materializing offscreen semantic-only nodes.

API

• Constructors inherited from VirtualLayout: range plus factory, state range plus factory, or count plus index factory.
• Fluent methods: .ScrollAxis, .ItemExtent, .EstimatedItemExtent, .CacheExtent, .Controller.
• Controller alignment: ScrollAlignment::Start, Center, or End.

Use ScrollView for a small heterogeneous document and VirtualGrid for multiple columns.

Constructor and configuration details

VirtualList(range, View(item)) stores the logical item source; the State-range form observes it. VirtualList(count, View(std::size_t index)) is useful when data is already indexed elsewhere. Captured values must remain valid for deferred item creation. Constructors and methods are declared in huxerui, <huxerui/view.h>.

Method	Contract
ScrollAxis(Axis)	Vertical by default; Horizontal uses widths as item extents.
ItemExtent(float)	Positive fixed extent for every item.
EstimatedItemExtent(float)	Positive initial estimate for variable measured extents.
CacheExtent(float)	Nonnegative extra realization distance around the viewport.
Controller(ScrollController)	Connects stable metrics and scroll operations.

Give the list a finite viewport and avoid nesting it in an unbounded ScrollView on the same axis. Fixed extents must match the intended row layout; estimates are refined as rows are measured. ScrollToItem(index, Start/Center/End) targets logical indices, and variable measurement may refine the offset after the request. A newer scroll request or direct manipulation cancels that pending alignment.

Offscreen lifetime

Virtualization can release item subtrees outside the realized/cache range. Stable keys preserve identity across compatible reconciliation, but are not an unlimited offscreen state store. Keep editable record data in the owning collection, not only in a row’s UseState. Lifecycle-owned row work may stop when that row is released; application-wide work needs a longer-lived owner.