Nodes

Nodes are the UI tree inside a surface. Each constructor (row { ... }, text { ... }) takes a property table and returns it tagged with its kind. This page covers layout and the properties every kind shares; each kind’s page covers what it adds. How a box looks is on paint, motion on animation, clicks and typing on input.

A bar with a left group, a centred clock and a right group:

local clock = state("clock", "12:00")

local function workspace(active)
    return rect { width = active and 18 or 8, height = 8, radius = 4, background = active and "#89B4FA" or "#45475A" }
end

local function status(name)
    return icon { name = name, size = 16, foreground = "#CDD6F4" }
end

local bar = panel {
    id = "bar",
    layer = "top",
    anchor = { top = true, left = true, right = true },
    exclusive_zone = 32,
    width = "fill",
    height = 32,
    child = row {
        width = "fill",
        height = "fill",
        padding = { left = 12, right = 12 },
        background = "#1E1E2ECC",
        children = {
            row { width = "fill", align_v = "center", spacing = 6, children = {
                workspace(true), workspace(false), workspace(false),
            } },
            text { content = clock, align_v = "center", font_weight = 700, foreground = "#CDD6F4" },
            row { width = "fill", align_h = "end", align_v = "center", spacing = 12, children = {
                status("network-wireless-symbolic"), status("audio-volume-high-symbolic"), status("bluetooth-active-symbolic"),
            } },
        },
    },
}

return { bar }

The two side rows are "fill", so they split what the clock leaves equally, and the clock sits at the exact centre whatever its width. The right row packs its children at its end.

Kinds

Every kind accepts the common properties. Box kinds also accept the box properties. Any other key raises an error: a typo such as aling_v asks “did you mean align_v?”, and a key close to nothing lists what the kind accepts. Keys inside a property table (anchor = { lefft = true }) and choice values (align_h = "cenetr") get the same suggestion.

The four surface roles (panel, window, popup, lock) are node kinds too: they take the common and box properties but margin, align_h and align_v, and stack their one child (surfaces).

Values

Layout model

A pass is one resolve of a surface: the engine re-runs the node tree’s signals, re-lays it out and repaints. It happens after a signal the surface reads changes (signals). Layout is flexbox, solved by taffy on every pass. Each container either flows its children along one axis or stacks them on top of each other.

A stacking parent’s content size is the union of its children, so a rect is how you layer a badge over an icon or a label over an image. A parent with its own size gives every child its content box, even a child larger than it.

Of the leaves, only text and icon measure themselves. image, capture, path, shader and textfield have no intrinsic width: without width they are 0 wide and draw nothing, and all but textfield need height too. A textfield defaults to one line of font_size tall.

Sizes

width and height take the same values.

There is no "content" literal; omit the property instead.

Children never shrink. Fixed and content-sized children that overflow a row keep their sizes and overflow it: they paint past a parent with no clip and are cut only when it sets one (a scroll viewport and a surface cut by default), and "fill" siblings get 0. A "fill" child along the main axis of a content-sized parent also gets 0: there is no remainder to share. Across the axis, "fill" in a content-sized parent takes the largest sibling’s size.

min_width, min_height, max_width and max_height are pixels [0, 8192] (not "fill" or percents). They clamp every size, content, fixed and "fill" alike, as in CSS: a "fill" capped by max_width leaves the rest to its "fill" siblings. A floor above a ceiling wins. Content past a ceiling overflows; a scroll on the same node scrolls it (scroll).

Spacing, padding and margin

padding and margin take a number for all four edges or { top, right, bottom, left } with missing edges 0. Negative margin is accepted; each padding edge must be within [0, 8192]. A hidden child adds no gap.

Alignment

align_h and align_v take "start", "center", "end" or "stretch", default "start", and act by axis:

"stretch" across an axis fills the slot and overrides a fixed size on that axis. To space items out along a row, use "fill" children as spacers.

text_align on text and textfield is separate: it places lines inside the node’s own box, and matters only when that box is wider than the text.

Common properties

The pointer handlers on_click, on_double_click, on_drag, on_wheel and submits_secure are here, so any node takes clicks: the innermost node under the pointer with a handler for the event wins, and a node without one lets the event through to the node around it (pointer).

scale, rotate and translate act like CSS transform: the subtree draws moved, while layout, siblings and geometry see the untransformed box. A node scaled to 0 takes no input. Tween them for motion that skips re-layout.

Cursor names

cursor takes the CSS cursor names that the Wayland cursor-shape protocol (wp_cursor_shape_v1) also uses. Any other string is refused.

The compositor draws the shape from its cursor theme.

Box properties

rect, row, column and the four surface roles also take background, radius, corner_shape, corner_smoothing, border_color, border_width, clip, mask, compositor_blur and shadow_mode, and effect.backdrop. They are documented on paint. Leaves and list take none of them: wrap one in a rect for a background, border or rounded clip.

Identity and reconciliation

Each pass walks the declared tree and matches it against the nodes on screen, one parent at a time. A matched node keeps its state: running tweens, a held image, a capture stream, a text field’s draft, and its resolved properties until a signal they read is written. An unmatched old node is removed, after its animate.exit if it has one (exit).

An id is a plain UTF-8 string, unique among its siblings (a duplicate is refused), never a signal. In a list, key supplies it. Give a node a stable id when:

• Siblings before it come and go. A position shift pairs it with the wrong old node.
• It holds state across changes: an image with retain or transition, a capture, a textfield.
• It replaces another node of the same kind. Two switched views that are both id-less columns match each other: the new view is the old node with new properties, so no exit or entry plays.

Showing, hiding and switching

visible = false takes a node out of layout, paint and input, with no gap. Its subtree stays in memory, frozen until it shows again. Use it for a section toggled in place; for views that replace each other, bind the parent’s children (switching views). opacity = 0 still takes space and input.

Switching views with ids

Views swapped through a children signal, each with its own id, so the outgoing one fades out while the incoming one fades in. The parent is a rect, so the two overlap during the swap instead of stacking. The shot switches tab to "bluetooth":

local tab = state("tab", "wifi")

local function page(name, title, icon_name, items)
    local rows = { text { content = title, font_size = 14, font_weight = 700, foreground = "#CDD6F4" } }
    for _, item in ipairs(items) do
        rows[#rows + 1] = row { spacing = 10, children = {
            icon { name = icon_name, size = 16, foreground = "#89B4FA", align_v = "center" },
            text { content = item, foreground = "#CDD6F4", align_v = "center" },
        } }
    end
    return column {
        id = name, -- a new id per view: the old view leaves and fades instead of being reused
        width = "fill",
        padding = 14,
        spacing = 10,
        radius = 12,
        background = "#1E1E2E",
        opacity = 1, -- `from` needs the property set
        animate = { opacity = { duration = 250, from = 0 }, exit = { duration = 250, opacity = 0 } },
        children = rows,
    }
end

local views = {
    wifi = function() return page("wifi", "Wi-Fi", "network-wireless-symbolic", { "Home", "Office 5G", "Cafe Guest" }) end,
    bluetooth = function()
        return page("bluetooth", "Bluetooth", "bluetooth-active-symbolic", { "Headphones", "Keyboard", "Phone" })
    end,
}

local body = rect {
    width = 260,
    children = tab:map(function(current) return { views[current]() } end),
}

return body

How do I…

Gotchas

See also: surfaces (where a tree lives), signals (live properties), paint, animation, input, capabilities.

Source: node vocabulary, layout solver, pass, reconciliation, property resolution, geometry parsers, transforms, hit testing and cursors (names from the cursor-icon crate), check.