list

A row or column whose children come from data: one each(item) call per element of items, up to limit. Use it for anything with a count you do not know up front: workspaces, notifications, search results, a thumbnail grid. For a fixed set of children, a row or column is simpler.

A scrolling thumbnail grid: a vertical list of two-image rows, decoded off-thread.

local paths = state("wallpapers", { "/usr/share/backgrounds/a.jpg", "/usr/share/backgrounds/b.jpg",
    "/usr/share/backgrounds/c.jpg", "/usr/share/backgrounds/d.jpg" })

-- Two per row: a vertical list of rows, keyed by the paths they hold.
local rows = paths:map(function(all)
    local out = {}
    for i = 1, #all, 2 do out[#out + 1] = { all[i], all[i + 1] } end
    return out
end)

local grid = list {
    width = 420,
    height = 300,
    spacing = 8,
    scroll = scroll("thumbs"),
    items = rows,
    key = function(pair) return table.concat(pair, "\n") end,
    each = function(pair)
        local tiles = {}
        for i, path in ipairs(pair) do
            tiles[i] = image { source = path, async = true, fit = "cover", width = 206, height = 116 }
        end
        return row { spacing = 8, children = tiles }
    end,
}

return grid

Keyed workspace buttons from a capability: workspaces cookbook.

Properties

list takes the common properties, plus the ones below. It takes no box properties: wrap it in a rect or column for a background.

A list packs and aligns exactly like the row or column its direction names: its own align_v (vertical) or align_h (horizontal) packs the items.

When items rebuild

A list keeps the items it built until something that build read changes. A pass that finds nothing changed calls no each and reads none of the items’ signals; it lays the kept items out again, about a third of the cost of building them. A change one item’s each read builds that item alone; a change the list itself read builds every item, or every item near the viewport in a long scrolling list. A signal bound to an item’s property is not the build’s: a write to it runs that property’s getter in each item that binds it and calls no each.

So bind a shared signal such as a theme color as the property, background = theme.bg, rather than reading it in each with theme.bg:get(): flipping the theme then costs one getter per row, not one each per row. A selection highlight follows the same rule: derive it per row, background = computed({ results, selected }, ...), rather than folding the selection into items, which builds every row on each move.

key carries each item’s state (tweens, a held image, a text field’s draft) onto its rebuilt node, and across reorders. Cap a long list with limit (a launcher’s top 50 matches), or hide it while closed so it freezes.

The engine sees signal reads only. An each, key or item map that reads the clock, a mutable variable or an items table changed in place keeps what it read until a signal it read is written. A delay or pulse builds the items that read it again on every pass while one is pending or open. What to read instead: what a node reads again.

Long scrolling lists

A list with both key and its own scroll builds only the items within a viewport of what it shows. The rest cost a key call when items changes, and scrolling, clamping and reveal behave as if every item were built. The first pass after the list appears builds everything once, to measure. An item scrolled further away loses its node: no animate.exit plays, and its tweens, keyboard focus and text field draft are dropped; when it comes back, each runs again but animate.from does not replay. Keep state that must survive in a named state.

How do I…

Scroll a long list

Bound the size on the scrolling axis, then bind a scroll signal. max_height lets the list shrink to fit a few items and scroll past 200 px.

local names = {}
for i = 1, 40 do names[i] = "Item " .. i end

local items = list {
    width = 240,
    max_height = 200, -- grows with its items up to 200 px, then scrolls
    spacing = 2,
    scroll = scroll("items"),
    items = names,
    each = function(name)
        return text { content = name, width = "fill", padding = 6 }
    end,
}

Gotchas

See also: row and column, signals, input: scroll.

Source: vocabulary, list parser, layout as row or column.