UI.List

UI.List(input: Input): Node

Creates a semantic collection whose direct children are ListItem nodes. Optional windowed mode realizes a bounded vertical viewport without introducing a feed-specific component.

Mental model

This is a declarative node: app.render describes it again from current state, while the host matches its stable id to the existing view.

Before you use it

Add luastra/ui to this module's dependencies in luastra.json, then import it with require("luastra/ui"). The project must declare the ui.render capability. app.render must return one UI.Screen root; place this node inside that tree rather than invoking it for a hidden side effect.

How it fits

The constructor validates its fields immediately and returns a UI.Node. After app.render returns, the host reconciles that node by stable id with the current semantic DOM-based interface. Current desktop and mobile hosts package the same web artifact; native adapters are used at capability boundaries.

Shared parameter groups

Parameters

Children and layout

Bounded retained list items with stable IDs.

Accessibility and keyboard

Creates a real list; provide label when a nearby heading does not make the list purpose clear. Windowed mode preserves logical positions and keeps a focused item realized.

Common mistakes

• Rendering an unbounded provider result instead of a bounded retained page.
• Changing ListItem IDs when the same logical item is re-rendered.

Returns

Node — a validated declarative UI node that becomes part of the next host-neutral render tree.

What happens next

A validated declarative node appears after it is returned as part of the current render tree.

Failures and fixes

Invalid fields, duplicate IDs, unsupported child combinations, or a missing ui.render capability fail during check, render-tree validation, or host startup.

Availability

Source API in 0.5.0-alpha; the public installer targets 0.5.0-alpha. Verify host-specific behavior against the selected SDK.

Focused example

UI.List {
    id = "results",
    label = "Search results",
    mode = "windowed",
    estimatedItemSize = 72,
    overscan = 6,
    itemCount = 1000,
    itemOffset = 200,
    endBusy = loadingNext,
    onEndReached = "results.next",
    table.unpack(retainedItems),
}

Continue learning

Complete inventory