Lists & streaming

Long lists and streaming text

A chat client is a very long list plus text that arrives a token at a time. Both now exist on the Rust side with tests behind them, and both are only half the story until the Compose interpreter catches up. This page says precisely which half you can rely on.

A plain list

A Column with a for loop over your data is correct and is fine for the hundreds of rows that fit an ordinary screen with some scrollback. It does not virtualise: every item becomes a real node on both sides.

rsx! {
    Column {
        fill_max_width: true,
        for message in messages() {
            Text { text: message }
        }
    }
}

Updating one message sends exactly one SetProp mutation and does not recompose its siblings, a tested requirement (FR-4), not an aspiration. The cost of this pattern is the node count, not the update path.

LazyColumn windowing Host side

A plain tree diff cannot keep a virtualised list virtual: the Host would have to describe items it never built in order for the renderer to know they exist. So for lazy lists the flow inverts.

1. The Host declares the total item count and a stable key per item.
2. The renderer decides which range is visible and asks for it with a RangeRequested event (event tag 7, 24 bytes).
3. The Host materialises subtrees for that range plus a buffer on each side, and nothing else.

Each item is wrapped in a Box node carrying an item_key string, which is what the renderer hands to Compose's LazyColumn as the item key. Scroll position and item identity stay in the renderer; the data stays in the Host. Scrolling back to an item you have already seen re-materialises an identical subtree.

rsx! {
    LazyColumn {
        item_count: messages.len(),
        buffer: 4,                                     // items kept on each side; default 4
        key_of: move |index| messages()[index].id.clone(),  // optional; defaults to the index
        item: move |index| rsx! {
            Text { text: messages()[index].body.clone() }
        },
    }
}

item and key_of are Callbacks, so a closure works directly. item_count is a usize; the wire carries it as an i64. Only item_count and item are required.

The acceptance criterion is concrete, and it passes: with 10,000 items and a request for 20 visible rows with a buffer of 4, the Host materialises 28 items, proportional to the window, not to the list. The test is fr8_node_count_is_proportional_to_the_window.

Streaming text Host side

An LLM response arrives token by token. Replacing the whole text property on every token re-sends the entire message each time, and the message grows, so the cost grows quadratically. The answer is an AppendText command on a Text node (mutation tag 8, 16 bytes) that carries only the new tail.

The Host coalesces: tokens that arrive between two frames merge into a single AppendText record per node, flushed in render_frame. A token never costs a batch of its own, and the accumulation buffers are reused so steady-state streaming does not allocate.

// Queue a tail for the next frame. Repeated calls coalesce into one record
// per node and into a single frame request.
host.append_text(node_id, " token");

Measured on the Host side: a 36 KB message stays under a 64-byte batch per token, and the p99 streaming frame is 125 ns. The full criterion, 100 appends per second with scrolling and typing staying smooth, is an end-to-end claim and has to wait for the renderer.

Streaming from a worker thread

This part is not speculative, and it matters more than either feature above. Domain work must not run on the UI thread, the thread that also runs your components and the whole boundary. PTY reads, HTTP, LLM streaming and file I/O belong on Host worker threads.

A worker's only job, as far as the UI is concerned, is to write to a signal. Waking the renderer is internal: the Host requests a frame for you, and repeated requests coalesce into a single render_frame call inside the Compose frame clock. User code never calls a boundary function, and there is no queue between the two sides to fill up.

The frame budget

The performance target is a comparison, not a number in isolation: the same screen written directly in Kotlin and Compose is the baseline, and this stack is allowed at most 10% more frame time than that, against an 8.33 ms budget on a 120 Hz display. A few of the budgets that shape how you write code:

Allocation is measured as a trend rather than an absolute: Dioxus allocates internally while diffing and dispatching (99 allocations per click, measured 2026-09-20), and Rust has no GC, so those allocations do not produce pauses. What matters is that repeating the same interaction does not increase the count. Growth means a leak or a cache that stopped working, and is investigated as a bug.