antle

Introduction

Mantle runs a desktop shell written in Lua on Wayland. Your shell.lua returns surfaces such as bars, windows and popups. Each surface holds nodes for layout and drawing. Signals keep their properties up to date as capabilities report changes.

The video is a Mantle shell: demo/director types each save and records the result. just demo records it again; The demo covers changing it.

Your first shell

Install Mantle, then create a config directory:

mantle init

Open ~/.config/mantle/shell.lua and replace its contents with this bar:

return panel {
    id = "bar",
    layer = "top",
    anchor = { top = true, left = true, right = true },
    width = "fill",
    height = 32,
    exclusive_zone = true,
    background = "#1e1e2e",
    child = row {
        width = "fill",
        height = "fill",
        padding = { left = 12, right = 12 },
        children = {
            text { content = "Mantle", font_weight = 700, foreground = "#89b4fa", align_v = "center" },
            rect { width = "fill" },
            text {
                content = mantle.clock:map(function(clock)
                    return os.date("%H:%M", clock.time)
                end, "--:--"),
                font_weight = 700,
                foreground = "#cdd6f4",
                align_v = "center",
            },
        },
    },
}

Check the config before starting a shell, then run it:

mantle check
mantle -d
mantle log -f

check evaluates and lays out the config without Wayland. It catches Lua and layout errors, but cannot test every value, callback or compositor response (what check covers). -d starts the shell detached; log -f follows its output. Change "Mantle" in shell.lua and save it. The bar reloads in place. If a save fails, the previous bar stays visible and the error goes to the log (reload behavior).

mantle init also writes .luarc.json so lua-language-server can complete the API and flag type mistakes (editor setup).

Where to go next

Every cookbook recipe is a complete shell.lua you can run on its own. The glossary defines terms used throughout the book.

Source: init, starter, check, watcher, reload.

Installation

Install both Mantle binaries, create a config, check it, and start the shell. The introduction provides a first bar to put in shell.lua.

Install

Releases carry the .deb, .rpm and tarball. mantle-bin packages each release; mantle-git and source builds follow main.

The mantle executable starts mantle-renderer from its own directory. Keep the two binaries from the same build together (binaries).

Set up a config

mantle init
mantle check

init writes shell.lua and .luarc.json under ~/.config/mantle by default. It keeps files that already exist; mantle init --force replaces them. Use -c DIR to work in another directory (config selection). Then edit shell.lua or copy the first bar into it. Run mantle check after edits to catch Lua and layout errors before starting the shell.

The .luarc.json points lua-language-server at the lua-meta/ stubs. A package installs them under $PREFIX/share/mantle/lua-meta. Otherwise init writes the binary’s embedded copy to $XDG_DATA_HOME/mantle/lua-meta and updates changed stubs. mantle check reports when those stubs need refreshing with mantle init. The editor config enables type, unbalanced, strict, global and unused-local warnings.

Run the shell

From a terminal inside your Wayland session:

mantle -d
mantle log -f

-d returns after starting the shell and prints its pid. log -f follows its output. Run mantle without -d to keep it in the foreground, or mantle stop to end a detached shell. The CLI explains logs, multiple running shells and command flags.

To start it with your compositor session, add one of these lines to that compositor’s config:

# niri
spawn-at-startup "mantle"
# Hyprland
exec-once = mantle

Start Mantle inside the compositor session so workspaces, windows and keyboard can find niri or Hyprland through that session’s environment.

Requirements

A capability starts when the config first reads mantle.<name>. You need only the backends for capabilities your config uses. Each capability page says what happens when its backend is missing.

clock, folders, storage and processes need nothing beyond the paths and programs the config names.

Build from source

A source build needs Rust 1.99 or later, a C compiler and pkg-config for vendored Lua, clang for PipeWire’s bindings, and development files for the linked libraries:

Use rustup where the distro’s cargo is older. Mantle is developed and run on Arch. The Fedora and Debian package lists build the workspace in a container; running the shell, and the updates capability’s dnf and apt backends, are untested on Fedora and Ubuntu.

System files

Packages install the files they need. The tarball puts them in /usr/local/share/mantle/, and a source build has them in packaging/. On Debian and Ubuntu, install the -debian variant of each PAM stack under the same name: they include common-* where the others include system-auth.

Gotchas

See also: introduction, CLI, FAQ.

Source: init, binaries, capability wiring, PAM worker.

CLI

The mantle binary starts the shell, checks a config without starting it, and lets a compositor keybind reach a running shell. Reach for set/toggle when a key should change what the shell shows, and call when it should make the shell do something.

A keybind workflow. The config declares the names:

-- `mantle toggle launcher_open` flips it; `mantle set launcher_open false` closes it.
local launcher_open = state("launcher_open", false)

-- `mantle toggle modal settings` opens "settings", or closes it when it is already open.
local modal = state("modal", "")

-- `mantle call volume.up` or `mantle call volume.up 10`.
action("volume.up", function(step)
    local audio = mantle.audio:get()
    for _, sink in ipairs(audio and audio.sinks or {}) do
        if sink.active and sink.volume then
            local volume = math.max(0, math.min(100, sink.volume + (step or 5)))
            mantle.audio:set_volume(sink.id, volume)
            return string.format("%d%%", math.floor(volume + 0.5))
        end
    end
    error("no default output yet")
end)

return panel {
    id = "launcher",
    layer = "overlay",
    keyboard_interactivity = "on_demand",
    visible = launcher_open,
    width = 480,
    height = 320,
    background = "#1e1e2eff",
    child = text {
        content = modal:map(function(name) return name == "" and "launcher" or name end),
        foreground = "#cdd6f4ff",
    },
}

The compositor binds keys to the commands; volume.up stands for an action your config defines. Hyprland (hyprland.conf):

bind = SUPER, Space, exec, mantle toggle launcher_open
bind = SUPER, Escape, exec, mantle set launcher_open false
bind = SUPER, Comma, exec, mantle toggle modal settings
bind = , XF86AudioRaiseVolume, exec, mantle call volume.up

Hyprland with a Lua config (0.56+):

hl.bind("SUPER + Space", hl.dsp.exec_cmd("mantle toggle launcher_open"))
hl.bind("SUPER + Comma", hl.dsp.exec_cmd("mantle toggle modal settings"))
hl.bind("XF86AudioRaiseVolume", hl.dsp.exec_cmd("mantle call volume.up"))

niri (config.kdl, inside binds { }):

Mod+Space repeat=false { spawn "mantle" "toggle" "launcher_open"; }
Mod+Escape { spawn "mantle" "set" "launcher_open" "false"; }
Mod+Comma repeat=false { spawn "mantle" "toggle" "modal" "settings"; }
XF86AudioRaiseVolume allow-when-locked=true { spawn "mantle" "call" "volume.up"; }

In a terminal, mantle call volume.up 10 prints the handler’s return value, such as 60%.

Commands

Flags and the command may come in any order. -V and -h win over anything after them.

Flags

A flag given to a command it does not apply to is an error, not ignored.

Log levels for a run:

MANTLE_LOG overrides the default level: MANTLE_LOG=debug, or per subsystem, MANTLE_LOG=warn,wayland=debug. Levels are off, error, warn, notice, info, debug (same as debug1) and debug2. An unknown entry is ignored with a warning. The config’s own log.* lines print at every level unless MANTLE_LOG names config=<level>.

Each log line reads HH:MM:SS LEVEL subsystem: message. Renderer lines prefix the subsystem with renderer/, config lines use config, and print output is written as is. The subsystem is the name MANTLE_LOG filters on (renderer/wayland: ... is wayland).

Environment variables

The Supervisor sets MANTLE_INSTANCE_DIR, MANTLE_GENERATION_ID, MANTLE_VERBOSE, MANTLE_PROFILE and MANTLE_CHECK on the Renderer it starts. They are internal; setting them by hand does nothing useful.

Binaries

Both must come from the same build. After rebuilding one, rebuild both.

Which config and which shell

The config directory resolves in this order, once at startup. Symlinks are resolved then, so retargeting one later does not move a running shell.

Several shells can run at once. Each running mantle holds an instance directory, $XDG_RUNTIME_DIR/mantle/<pid>-<start ms>/, with its control socket, its log (shell.log), the config path it runs, and a lock that marks it as running. mantle list prints its name under DIR. Client commands pick one:

A stopped run’s log stays until logout clears $XDG_RUNTIME_DIR. mantle log says so when it prints one.

Values and arguments

set, toggle and call read each value as JSON when it parses, else as a plain string.

call passes any number of arguments to the handler in order. Its output:

The handler contract is in action.

set and toggle wait for the shell to apply the write, up to 5 s like call. The shell refuses a write to a name the config does not declare, a bare toggle on a non-boolean, or a value that fails the scalar checks. A refusal prints state `name` refused: <reason> on stderr, exits 1 and is also a warning in mantle log. What toggle <name> <value> compares and restores follows named state: scalars compare by value (1 equals 1.0), and a table never equals, so toggling to a table always sets it.

A write that changes the value runs the state’s on_change handlers before the shell repaints, the same as a write from Lua. They run after the command has its answer, so a raising handler is a warning in mantle log, not a refusal.

What check covers

mantle check evaluates shell.lua and its requires exactly as a start does, with no Wayland, no GPU, and every capability reading nil. Then it lays every surface out four times with the real layout code, on one 1920x1080 output plus one per output name a panel pins:

In the sample passes, reading a field a capability’s state does not have raises, naming the nearest one: mantle.audio:get().sinks[1] has no `volum`: did you mean `volume`?. A running shell reads nil there, so a field removed by an engine update fails the check instead of hiding. An on_change handler runs on each push, and its error fails the pass; a running shell only logs it.

It prints <path>: ok, N surface(s) and one <role> <id> line per surface, preceded by anything the config printed, then one warning: line per outer shadow the surface cuts off by 4 px or more, naming the side and the room it needs. A warning leaves the exit status at 0, and a side where a panel meets the output edge is skipped. An error prints as <config dir>: <error> and exits 1; files in it are named relative to the config directory. A layout error leads with the line that built the failing node and its kind (text[1], with its index among children), then gives the path down to its parent and the surface instance. An error that only some passes hit ends with those passes on a line of its own, (<pass>, <pass>); one every pass hits, such as a typo, names none. With more than one broken node, <error> is N nodes failed: and then one node per line: the first 20, then and N more. A mistake repeated on every output, or by every item of a list, is listed once. The path names the line that built each node (a lone child has no index) and, for a failing :map or computed, the line that created the signal:

/home/me/.config/mantle: widgets/bar.lua:4: attempt to perform arithmetic on a nil value
stack traceback:
	widgets/bar.lua:4: in function 'widgets.bar.build'
	shell.lua:2: in main chunk
/home/me/.config/mantle: shell.lua:2: text[1]: no property `contnet`; did you mean `content`? (at panel (shell.lua:7) > row (shell.lua:7) on `bar@DP-1`)
/home/me/.config/mantle: shell.lua:9: text: invalid value for `content`: Signal getter on a `text` node failed: signal created at shell.lua:3: shell.lua:4: attempt to index a number value (local 'n') (at panel (shell.lua:9) on `bar@DP-1`)
stack traceback:
	shell.lua:4: in function <shell.lua:3>

When the stubs mantle init wrote differ from this mantle, check also prints one line asking you to run mantle init again.

Under an error line that starts with file.lua:N:, check prints that source line, trimmed, after |.

It starts no programs and writes no state. On failure it prints only the error, not the config’s print output.

Injecting input

mantle input <surface> <verb> ... feeds events to one surface through the code real input runs: hit testing, hover, on_press, on_click, on_drag, on_wheel, focus and textfield editing. It never reaches another client, moves the real pointer or cursor, or takes the compositor’s keyboard focus.

<surface> is the id the config declares. A surface with an instance per output is named id@output; the bare id works only while one instance is shown. A hidden surface is not found. Click a textfield to focus it, then type or key; each command is one request, and the scene re-resolves between requests, not between the steps of one.

A click or key can change which field or control that surface has focused. Focus on another surface is kept, unless the injection focuses something of its own: one field holds focus at a time. Pointer state stays where injected input left it, hover and pointer(name) included, until a leave or real pointer motion; a press with no release stays held the same way.

Refused, with an error on stderr and exit 1:

• a lock surface;
• a press or release over a secure_submit field or a submits_secure = true node, and any key or type while a secure_submit field holds focus, including the real keyboard’s;
• ctrl+c and ctrl+v, which need the compositor’s clipboard;
• an unknown, ambiguous or hidden surface, a pointer button with no position, a bad combo or a modifier other than ctrl and shift.

Injected presses carry no compositor serial. A popup with grab = true, or toplevel(id):move(), :resize() and :show_menu() called from the press, warn in mantle log and do nothing; the rest of the press runs.

Exit codes

How do I…

…wire a keybind? Declare a state or an action, then bind the command in the compositor, as in the example at the top. Use set/toggle to change what is shown, call to make the shell act. niri’s repeat=false keeps a held key from toggling repeatedly.

…start or stop the shell? Start it from the compositor (run the shell), which gives it XDG_RUNTIME_DIR and the Wayland socket. From a terminal, mantle -d starts it and gives the prompt back. Stop it with Ctrl-C in the foreground, or mantle stop (-c or --pid picks one of several). A config stops its own shell with process.detach("mantle", { "stop", "--pid", tostring(mantle.pid) }), which outlives the shell it stops.

…read the logs? mantle log prints the whole log of the current shell. mantle log -f follows it. Errors raised in callbacks are warnings, so they show by default. For more detail, restart with mantle -v (info) or mantle -vv (debug). mantle log | grep 'renderer/config: ' keeps only the config’s own log.* lines.

…debug a reload that did nothing? Run mantle check, then mantle log. The full sequence is in runtime.

…target one of two running shells?

$ mantle list
PID     UPTIME  DIR                    CONFIG
4120    2h13m   4120-1727170000000     /home/me/.config/mantle
9051    41s     9051-1727177900000     /home/me/src/mantle-test
$ mantle --pid 9051 toggle launcher_open
$ mantle -c ~/src/mantle-test call volume.up
$ mantle log --pid 9051 -f

…try a config without touching the running shell? mantle check -c ~/src/mantle-test first, then mantle -c ~/src/mantle-test starts a second shell on it. Its surfaces draw beside the first shell’s, so give them other ids or anchors, and address it with -c or --pid.

…see what a keybind can reach? mantle call lists the actions and mantle set the states with their values. Both print nothing when the config declares none, so they pipe into a picker: mantle call | fzf | xargs mantle call.

$ mantle set
launcher_open	false
modal	"settings"

…set a string that looks like a number or boolean? Quote it as JSON: mantle set label '"42"'.

…use an action’s answer in a script? volume=$(mantle call volume.up) captures the printed value, and a non-zero exit means it failed.

…see which node has the wrong size? Run MANTLE_DUMP_LAYOUT=bar@eDP-1 mantle -vvv and read mantle log. The instance id is the surface id, @, and the output name.

…get completion and type checking in an editor? Set up a config.

Gotchas

See also: runtime · named state · action · capabilities · glossary for Supervisor, Renderer and generation.

Source: argument parsing, commands, shell selection, set/toggle/call/input client, state writes, input injection, check, init, log, levels.

Working with coding agents

A coding agent can edit a Mantle config, check it, watch it reload and drive the result, all from a shell, without a screenshot or a human at the keyboard. Every step below is a command from the CLI; none is agent-specific.

The loop

1. Discover

With a shell running:

$ mantle list
PID     UPTIME  DIR                    CONFIG
4242    3m      4242-1760000000000     /home/me/.config/mantle
$ mantle call
volume.up
$ mantle set
launcher_open	false
modal	""

mantle call with no name prints each action the config declares, one per line, sorted. mantle set (or toggle) with no name prints each state as name<TAB>JSON; strings are quoted, so the line can be passed back as mantle set <name> <value>. mantle list shows running shells, oldest first. After a failed reload, both lists describe what the shell still runs (reload rules).

Run mantle init once. It writes .luarc.json and, unless packaged stubs exist, the type stubs to $XDG_DATA_HOME/mantle/lua-meta, so lua-language-server shows the agent the exact API names, property names and capability fields instead of guesses.

2. Extend

Declare a state for something the UI shows and an action for something the shell does. Both are reachable from the command line, so the agent can test them before wiring a key:

local count = state("clicks", 0)

action("clicks.bump", function(by)
    local n = count:get() + (tonumber(by) or 1)
    count:set(n)
    log.info("clicks is now", n)
    return n
end)

return panel {
    id = "counter",
    layer = "top",
    anchor = { top = true, left = true },
    width = 120,
    height = 32,
    child = text { content = count:map(function(n) return "clicks: " .. n end) },
}

mantle call clicks.bump 2 prints the return value: a string bare, anything else as JSON, nothing for nil (call output). A raise prints `name` failed: <reason> on stderr and exits 1.

The Lua logging functions are log.error, log.warn, log.info and log.debug (log). They print at every level, as HH:MM:SS LEVEL config: message with the arguments tab-joined. print also lands in mantle log, unstamped.

3. Validate

$ mantle check
/home/me/.config/mantle/shell.lua: ok, 1 surface(s)
  panel   counter

mantle check runs the same evaluation and layout code as a start, with no Wayland, no GPU and no subprocesses, so it is safe while the real shell runs. It lays every surface out in four passes (capabilities nil, sample data, alternate sample data, empty lists), which catches the missing-data and empty-list branches an agent rarely reads back. It exits 0 when clean and 1 on an error, printing <config dir>: <error>, with file:line and, for a mistyped property, a suggestion:

/home/me/.config/mantle: shell.lua:16: text: no property `contnet`; did you mean `content`? (at panel (shell.lua:15) on `counter@DP-1`)

Details: What check covers. -c DIR checks another directory.

4. Apply

Saving any .lua or .frag file under the config directory reloads the running shell 200 ms after the last write. Other extensions do not. Read the result:

$ mantle log -f
12:01:07 NOTICE renderer/socket: shell reloaded

A reload that raises or whose scene is rejected is logged as an error, and the previous scene stays on screen (failure table). It also drops the old evaluation’s actions, so mantle call after a failure may not find a name that worked a minute ago. The fix is to correct the file and save again.

5. Drive

mantle input <SURFACE> <VERB> goes through the same hit testing, hover, on_click, on_drag and textfield code as a real pointer, in the surface’s logical pixels, and never moves the real cursor or takes compositor focus. <SURFACE> is the declared id, or id@output when one id has an instance per output. Lock surfaces and secure_submit fields refuse input. All verbs: Injecting input.

With several shells running, --pid <pid> (from mantle list) picks one, and -c <dir> picks the newest on that config. They cannot be combined. The selection rules cover the default.

Instructions to paste

For CLAUDE.md, AGENTS.md or the equivalent:

This repo is a Mantle shell config (Lua). Docs: https://anasgets111.github.io/mantle/
- Run `mantle init` once; read the stubs it points `.luarc.json` at for exact API names before guessing.
- Before saving a change to shell.lua, run `mantle check`; it must exit 0.
- After saving, run `mantle log` and look for "shell reloaded"; any error line means the old scene is still on screen.
- Add `action("name", fn)` for behavior you want to test. Run it with `mantle call name [args]`.
- Use `mantle set`/`toggle` and `mantle input <surface> <verb>` to exercise the UI. Do not run `mantle stop` or start a second shell.
- Use log.info/log.warn, not print, for debug output.

Source: CLI, check, log.

Cookbook

Complete widgets to copy, simplest first. Each recipe is a whole shell.lua: save it in a config directory, run mantle check -c <dir>, then start the shell. New to Mantle? The introduction builds a first bar step by step.

To combine recipes, keep one bar panel and put each recipe’s bar widgets in its row. Copy every other surface across as it is.

Clock bar

A bar across the top of every monitor with a clock in the centre. Clicking the clock switches between the time and the full date, and hovering it shows the date in a tooltip.

local show_date = state("clock_show_date", false)
local clock_hover = hover("clock")

local label = computed({ mantle.clock, show_date }, function(clock, date)
    return os.date(date and "%A %d %B" or "%H:%M", clock.time)
end, "--:--")

local tooltip_text = mantle.clock:map(function(clock)
    return os.date("%A, %d %B %Y", clock.time)
end, "")

local clock = rect {
    align_v = "center",
    padding = { left = 10, right = 10, top = 4, bottom = 4 },
    radius = 6,
    hover = clock_hover,
    background = clock_hover:map(function(on) return on and "#313244" or "#00000000" end),
    animate = { background = 120 },
    on_click = function() show_date:set(not show_date:get()) end,
    children = { text { content = label, font_size = 14, foreground = "#cdd6f4" } },
}

local bar = panel {
    id = "bar",
    layer = "top",
    anchor = { top = true, left = true, right = true },
    width = "fill",
    height = 32,
    exclusive_zone = true,
    child = row {
        width = "fill",
        height = "fill",
        padding = { left = 8, right = 8 },
        background = "#1e1e2e",
        children = { rect { width = "fill" }, clock, rect { width = "fill" } },
    },
}

local tooltip = popup {
    id = "clock_tooltip",
    parent = "bar",
    anchor_rect = hover_rect("clock"),
    anchor = "bottom",
    gravity = "bottom",
    offset = { y = 6 },
    grab = false,
    visible = clock_hover,
    padding = 8,
    radius = 8,
    background = "#1e1e2e",
    border_width = 1,
    border_color = "#45475a",
    child = text { content = tooltip_text, foreground = "#cdd6f4" },
}

return { bar, tooltip }

How it works

• mantle.clock pushes the time once a second, and os.date formats it (clock).
• computed combines the clock with a named state the click toggles (derived signals).
• Both "fill" spacers take an equal share of the row, so the clock sits at the exact centre (sizes).
• The background is on the row, not the panel, so the whole bar takes clicks (input region).
• hover and hover_rect drive a non-grabbing popup as a tooltip (hover).

Variations

Battery indicator

A bar pill with a battery icon and percentage that turns red when low, a tooltip with the charge state and time left, and a desktop notification when the charge drops past 15%. On a desktop with no battery the pill hides itself.

local LOW = 15
local pill_hover = hover("battery")

local STATES = {
    charging = "Charging",
    discharging = "On battery",
    fully_charged = "Fully charged",
    pending_charge = "Plugged in, not charging",
    empty = "Empty",
}

local function duration(seconds)
    local hours, minutes = seconds // 3600, seconds % 3600 // 60
    return hours > 0 and string.format("%d h %02d min", hours, minutes) or string.format("%d min", minutes)
end

-- Adwaita-style names: battery-level-0 to battery-level-100 in steps of 10.
local glyph = mantle.battery:map(function(battery)
    if not battery.present then
        return "battery-missing-symbolic"
    end
    local step = math.floor(battery.percent / 10 + 0.5) * 10
    if battery.state == "fully_charged" or (step == 100 and battery.state == "charging") then
        return "battery-level-100-charged-symbolic"
    end
    return string.format("battery-level-%d%s-symbolic", step, battery.state == "charging" and "-charging" or "")
end, "battery-missing-symbolic")

local colour = mantle.battery:map(function(battery)
    local low = battery.present and battery.percent <= LOW and battery.state == "discharging"
    return low and "#f38ba8" or "#cdd6f4"
end, "#cdd6f4")

local details = mantle.battery:map(function(battery)
    if not battery.present then
        return "No battery"
    end
    local line = string.format("%d%% · %s", battery.percent, STATES[battery.state] or battery.state)
    if battery.state == "discharging" and battery.time_to_empty then
        line = line .. "\n" .. duration(battery.time_to_empty) .. " left"
    elseif battery.state == "charging" and battery.time_to_full then
        line = line .. "\n" .. duration(battery.time_to_full) .. " to full"
    end
    return line
end, "No battery")

-- Warn once each time the charge falls past LOW while draining.
mantle.battery:on_change(function(battery, previous)
    if previous == nil or not battery.present then
        return
    end
    if battery.state == "discharging" and battery.percent <= LOW and previous.percent > LOW then
        process.detach("notify-send", { "-u", "critical", "Battery low", battery.percent .. "% remaining" })
    end
end)

local pill = row {
    align_v = "center",
    spacing = 4,
    padding = { left = 8, right = 10, top = 3, bottom = 3 },
    radius = 12,
    background = pill_hover:map(function(on) return on and "#45475a" or "#313244" end),
    hover = pill_hover,
    visible = mantle.battery:map(function(battery) return battery.present end, false),
    children = {
        icon { name = glyph, size = 16, foreground = colour, align_v = "center" },
        text {
            content = mantle.battery:map(function(battery)
                return battery.present and battery.percent .. "%" or ""
            end, ""),
            foreground = colour,
            align_v = "center",
        },
    },
}

return {
    panel {
        id = "bar",
        layer = "top",
        anchor = { top = true, left = true, right = true },
        width = "fill",
        height = 32,
        exclusive_zone = true,
        child = row {
            width = "fill",
            height = "fill",
            padding = { left = 8, right = 8 },
            background = "#1e1e2e",
            children = { rect { width = "fill" }, pill },
        },
    },
    popup {
        id = "battery_tooltip",
        parent = "bar",
        anchor_rect = hover_rect("battery"),
        anchor = "bottom",
        gravity = "bottom",
        offset = { y = 6 },
        grab = false,
        visible = pill_hover,
        padding = 8,
        radius = 8,
        background = "#1e1e2e",
        border_width = 1,
        border_color = "#45475a",
        child = text { content = details, foreground = "#cdd6f4", wrap = "word" },
    },
}

How it works

• mantle.battery reads present = false on a desktop, and a map gives before for the time before its first push (battery).
• state names UPower’s charge state; time_to_empty and time_to_full are optional and need their own guard.
• The icon is picked by name from the icon theme and tinted with foreground (icon).
• on_change compares with the previous push to fire only on the downward crossing (on_change); process.detach runs notify-send (process.detach).
• The tooltip is a non-grabbing popup anchored to hover_rect (hover).

Variations

Volume OSD

A card near the bottom of the focused monitor that shows the volume for a moment whenever it changes, whether from a media key, wpctl or a mixer. It fades and slides in, then out.

-- The last change worth showing. `n` makes every write differ: `:set` skips a table equal to the held one.
local osd = state("volume_osd", { volume = 0, muted = false, n = 0 })

local function default_sink(audio)
    for _, sink in ipairs(audio.sinks) do
        if sink.active then
            return sink
        end
    end
end

mantle.audio:on_change(function(audio, previous)
    local sink, before = default_sink(audio), previous and default_sink(previous)
    if before == nil or sink == nil or sink.id ~= before.id or before.volume == nil or sink.volume == nil then
        return -- the first push, or a new default, is learned state, not a change
    end
    if sink.volume ~= before.volume or sink.muted ~= before.muted then
        osd:set({ volume = sink.volume, muted = sink.muted, n = osd:get().n + 1 })
    end
end)

local shown = pulse(osd, 1500) -- true for 1.5 s after each change
local mapped = pulse(osd, 1700) -- keeps the surface up while the card fades out

local function percent(entry)
    return math.floor(math.min(entry.volume, 100) + 0.5)
end

local glyph = osd:map(function(entry)
    if entry.muted or entry.volume == 0 then
        return "audio-volume-muted-symbolic"
    end
    local level = percent(entry)
    return level < 34 and "audio-volume-low-symbolic"
        or level < 67 and "audio-volume-medium-symbolic"
        or "audio-volume-high-symbolic"
end)

return {
    panel {
        id = "volume_osd",
        layer = "overlay",
        output = "active",
        anchor = { bottom = true }, -- no left/right: centred, width measured
        margin = { bottom = 68 },
        padding = { bottom = 12 }, -- room for the card's 12 px slide, which the surface would clip
        visible = mapped,
        child = row {
            width = 280,
            height = 48,
            spacing = 12,
            padding = { left = 16, right = 16 },
            align_v = "center",
            radius = 24,
            background = "#1e1e2ee6",
            border_width = 1,
            border_color = "#45475a",
            opacity = shown:map(function(on) return on and 1 or 0 end),
            translate = shown:map(function(on) return { y = on and 0 or 12 } end),
            animate = {
                opacity = { duration = 150, from = 0 },
                translate = { duration = 200, easing = "out_cubic", from = { y = 12 } },
            },
            children = {
                icon { name = glyph, size = 20, foreground = "#cdd6f4", align_v = "center" },
                rect {
                    width = "fill",
                    height = 6,
                    radius = 3,
                    align_v = "center",
                    background = "#45475a",
                    children = {
                        rect {
                            height = "fill",
                            radius = 3,
                            background = osd:map(function(entry) return entry.muted and "#6c7086" or "#89b4fa" end),
                            width = osd:map(function(entry) return percent(entry) .. "%" end),
                            animate = { width = { duration = 120 } },
                        },
                    },
                },
                text {
                    content = osd:map(function(entry) return entry.muted and "Muted" or percent(entry) .. "%" end),
                    width = 44,
                    text_align = "end",
                    align_v = "center",
                    font_size = 13,
                    foreground = "#cdd6f4",
                },
            },
        },
    },
}

Bind the volume keys to anything that changes the default sink, for example wpctl set-volume -l 1 @DEFAULT_AUDIO_SINK@ 5%+; the OSD follows the push.

How it works

• on_change reacts to each audio push and follows the active sink. It skips the first push, a new default and a sink’s first volume report, which are learned state (on_change, audio).
• It writes a fresh table, counted by n, into a named state; pulse reads true for a while after each change (pulse).
• A longer second pulse keeps the surface mapped while the card fades, since hiding a surface plays no exit (delay is the general form).
• output = "active" shows it on the output the compositor picks, usually the focused one, and a bottom-only anchor centres it (panel output, OSD).
• The fill is a "NN%" width inside a fixed track (sizes); translate and opacity animate without re-laying out (animation).
• The glyph comes from the icon theme by name (icon).

Variations

Workspaces

A bar on every monitor listing that monitor’s workspaces, on every supported compositor. The active workspace is a wide pill, occupied ones are brighter, a click focuses one and the wheel steps through them. On Hyprland, special workspaces get their own toggles.

-- The workspaces of one output, `nil` until the compositor answers.
local function output_of(workspaces, name)
    for _, output in ipairs(workspaces and workspaces.outputs or {}) do
        if output.name == name then
            return output
        end
    end
end

local function focus_step(name, step)
    local output = output_of(mantle.workspaces:get(), name)
    if output == nil then
        return
    end
    for index, workspace in ipairs(output.workspaces) do
        if workspace.id == output.active_workspace then
            local target = output.workspaces[math.max(1, math.min(#output.workspaces, index + step))]
            if target then
                mantle.workspaces:focus(target.id)
            end
            return
        end
    end
end

local function strip(name)
    local wheel = 0 -- partial notches from a touchpad or high-resolution wheel
    return rect {
        align_v = "center",
        -- Wheel up is positive; step towards lower numbers, once per whole notch.
        on_wheel = function(_, steps)
            wheel = wheel + steps
            local notches = math.modf(wheel) -- whole notches; the fraction carries over
            if notches == 0 then return end
            wheel = wheel - notches
            focus_step(name, -math.tointeger(notches))
        end,
        children = {
            list {
                direction = "horizontal",
                spacing = 4,
                align_v = "center",
                items = mantle.workspaces:map(function(workspaces)
                    local output = output_of(workspaces, name)
                    local items = {}
                    for index, workspace in ipairs(output and output.workspaces or {}) do
                        items[index] = {
                            id = workspace.id,
                            label = tostring(workspace.number or workspace.name), -- draw number, send id
                            active = workspace.id == output.active_workspace,
                            populated = workspace.populated,
                        }
                    end
                    return items
                end),
                key = function(item) return tostring(item.id) end,
                each = function(item)
                    return rect {
                        width = item.active and 36 or 22,
                        height = 20,
                        radius = 10,
                        background = item.active and "#89b4fa" or (item.populated and "#45475a" or "#313244"),
                        animate = { width = { duration = 180, easing = "out_cubic" }, background = 180 },
                        on_click = function() mantle.workspaces:focus(item.id) end,
                        children = {
                            text {
                                content = item.label,
                                align_h = "center",
                                align_v = "center",
                                font_size = 11,
                                foreground = item.active and "#1e1e2e" or "#cdd6f4",
                            },
                        },
                    }
                end,
            },
        },
    }
end

-- Hyprland's scratchpads; `special` is nil on niri, so this list is empty there.
local specials = list {
    direction = "horizontal",
    spacing = 4,
    align_v = "center",
    items = mantle.workspaces:map(function(workspaces)
        return workspaces.special
    end),
    key = function(special) return special.name end,
    each = function(special)
        local short = special.name:gsub("^special:?", "") -- "special:scratch" -> "scratch"
        return rect {
            padding = { left = 8, right = 8, top = 2, bottom = 2 },
            radius = 10,
            background = special.shown_on and "#f9e2af" or "#313244",
            on_click = function() mantle.workspaces:toggle_special(special.name) end,
            children = {
                text {
                    content = short ~= "" and short or "special",
                    font_size = 11,
                    foreground = special.shown_on and "#1e1e2e" or "#cdd6f4",
                },
            },
        }
    end,
}

return {
    panel {
        id = "bar",
        layer = "top",
        anchor = { top = true, left = true, right = true },
        width = "fill",
        height = 32,
        exclusive_zone = true,
        child = function(output) -- one instance per monitor, named by connector
            return row {
                width = "fill",
                height = "fill",
                spacing = 12,
                padding = { left = 8, right = 8 },
                background = "#1e1e2e",
                children = { strip(output), specials },
            }
        end,
    },
}

How it works

• child = function(output) builds one bar per monitor and passes its connector name (per-output child).
• outputs[].name matches that connector; active_workspace is the id shown there (workspaces).
• The list rebuilds its buttons from the mapped array, and key keeps each button’s tweens when workspaces come and go (list).
• Labels draw number (or name) and clicks send id: ids are opaque strings (workspaces gotchas).
• on_wheel on the outer rect reads the live state with :get() inside the handler (pointer).
• The width tween makes the active pill grow in place (animation).

Variations

Lock screen

A lock screen on every monitor with a large clock, the date and a password card that reports checking and wrong passwords. It fades in when the session locks and out after a correct password. It locks from a keybind (mantle call lock) and after five minutes idle.

local FADE_MS = 250

mantle.lock:set_unlock_animation(FADE_MS)
mantle.idle:register_threshold(300, function() mantle.lock:lock() end, function() end)
action("lock", function() mantle.lock:lock() end)

-- Up while locked and not yet unlocking: drives the fade both ways.
local up = mantle.lock:map(function(lock) return lock.active and not lock.unlocking end, false)

local time = mantle.clock:map(function(clock) return os.date("%H:%M", clock.time) end, "")
local date = mantle.clock:map(function(clock) return os.date("%A, %d %B", clock.time) end, "")

local hint = mantle.lock:map(function(lock)
    local last = lock.messages[#lock.messages]
    if lock.authenticating then
        return "Checking…"
    elseif last then
        return last.text
    elseif lock.error ~= "" then
        return lock.attempts > 1 and string.format("Wrong password (%d tries)", lock.attempts) or "Wrong password"
    end
    return lock.prompt and lock.prompt.text or "Type your password and press Enter"
end, "")

local failed = mantle.lock:map(function(lock) return lock.error ~= "" and not lock.authenticating end, false)

local lock_screen = lock {
    id = "lock",
    background = "#11111b",
    child = function(output)
        return column {
            width = "fill",
            height = "fill",
            align_h = "center",
            align_v = "center",
            spacing = 16,
            background = { gradient = "linear", angle = 160, stops = { { 0, "#1e1e2e" }, { 1, "#11111b" } } },
            opacity = up:map(function(on) return on and 1 or 0 end),
            animate = { opacity = { duration = FADE_MS, from = 0 } },
            children = {
                text { content = time, font_size = 96, foreground = "#cdd6f4", align_h = "center" },
                text { content = date, font_size = 20, foreground = "#a6adc8", align_h = "center" },
                rect { height = 32 },
                text { content = os.getenv("USER") or "", font_size = 16, foreground = "#cdd6f4", align_h = "center" },
                rect {
                    width = 320,
                    align_h = "center",
                    padding = { left = 16, right = 16 },
                    radius = 22,
                    background = "#1e1e2e",
                    border_width = 2,
                    border_color = failed:map(function(bad) return bad and "#f38ba8" or "#45475a" end),
                    animate = { border_color = 150 },
                    children = {
                        textfield {
                            width = "fill",
                            height = 44,
                            font_size = 16,
                            foreground = "#cdd6f4",
                            text_align = "center",
                            placeholder = "Password",
                            masked = mantle.lock:map(function(lock) return not (lock.prompt and lock.prompt.echo) end, true),
                            secure_submit = { capability = "lock", action = "authenticate" },
                        },
                    },
                },
                text {
                    content = hint,
                    foreground = failed:map(function(bad) return bad and "#f38ba8" or "#6c7086" end),
                    align_h = "center",
                },
            },
        }
    end,
}

return { lock_screen }

How it works

• Declaring a lock does not lock; mantle.lock:lock() does, and only a correct password in the one secure field unlocks (lock surface, lock capability).
• secure_submit sends keystrokes straight to PAM; Lua never sees the password, so the field has no on_change or on_submit (secure fields).
• child = function(output) gives every monitor its own copy (per-output child).
• set_unlock_animation keeps the lock up for FADE_MS after success, while unlocking fades the card out (animation).
• PAM starts when the session locks. The hint shows its latest messages line (a faillock countdown, say) or else its prompt text, and error, attempts and authenticating drive the rest of the hint and the red border.
• masked follows prompt.echo, so a two-factor code shows as typed while a password stays masked. Either way it never reaches Lua (lock capability).
• action exposes mantle call lock to a keybind, and an idle threshold locks after 300 s without input (action, idle).

Variations

Power menu

A full-screen overlay with lock, suspend, log out, restart and power off. The last three ask for a second click before they run, and a click outside the buttons closes the menu. A bar button opens it, and so does mantle toggle power_menu_open from a keybind.

local open = state("power_menu_open", false)
local pending = state("power_menu_pending", "") -- the action waiting for its second click

local function close()
    open:set(false)
end

local function log_out()
    local workspaces = mantle.workspaces:get()
    local compositor = workspaces and workspaces.compositor
    if compositor == "niri" then
        process.detach("niri", { "msg", "action", "quit", "--skip-confirmation" })
    elseif compositor == "hyprland" then
        process.detach("hyprctl", { "dispatch", "exit" })
    end
end

local ACTIONS = {
    { key = "lock", label = "Lock", glyph = "system-lock-screen-symbolic",
      run = function() mantle.lock:lock() end },
    { key = "suspend", label = "Suspend", glyph = "weather-clear-night-symbolic",
      run = function() process.detach("systemctl", { "suspend" }) end },
    { key = "logout", label = "Log out", glyph = "system-log-out-symbolic", confirm = true, run = log_out },
    { key = "reboot", label = "Restart", glyph = "system-reboot-symbolic", confirm = true,
      run = function() process.detach("systemctl", { "reboot" }) end },
    { key = "poweroff", label = "Power off", glyph = "system-shutdown-symbolic", confirm = true,
      run = function() process.detach("systemctl", { "poweroff" }) end },
}

local function action_button(action)
    local over = hover("power_" .. action.key)
    local armed = pending:map(function(key) return key == action.key end)
    return rect {
        width = 120,
        height = 120,
        radius = 20,
        hover = over,
        background = computed({ over, armed }, function(hovered, is_armed)
            if is_armed then return "#f38ba8" end
            return hovered and "#45475a" or "#313244"
        end),
        animate = { background = 120, scale = { duration = 120, easing = "out_cubic" } },
        scale = over:map(function(hovered) return hovered and 1.05 or 1 end),
        on_click = function()
            if action.confirm and pending:get() ~= action.key then
                pending:set(action.key)
                return
            end
            close()
            action.run()
        end,
        children = {
            column {
                align_h = "center",
                align_v = "center",
                spacing = 10,
                children = {
                    icon {
                        name = action.glyph,
                        size = 36,
                        align_h = "center",
                        foreground = armed:map(function(is_armed) return is_armed and "#1e1e2e" or "#cdd6f4" end),
                    },
                    text {
                        content = armed:map(function(is_armed) return is_armed and "Click again" or action.label end),
                        align_h = "center",
                        foreground = armed:map(function(is_armed) return is_armed and "#1e1e2e" or "#cdd6f4" end),
                    },
                },
            },
        },
    }
end

local buttons = {}
for index, action in ipairs(ACTIONS) do
    buttons[index] = action_button(action)
end

return {
    panel {
        id = "bar",
        layer = "top",
        anchor = { top = true, left = true, right = true },
        width = "fill",
        height = 32,
        exclusive_zone = true,
        child = row {
            width = "fill",
            height = "fill",
            padding = { left = 8, right = 8 },
            background = "#1e1e2e",
            children = {
                rect { width = "fill" },
                rect {
                    align_v = "center",
                    padding = 6,
                    radius = 6,
                    on_click = function() open:set(true) end,
                    children = { icon { name = "system-shutdown-symbolic", size = 16, foreground = "#f38ba8" } },
                },
            },
        },
    },
    panel {
        id = "power_menu",
        layer = "overlay",
        output = "active",
        anchor = { top = true, bottom = true, left = true, right = true },
        width = "fill",
        height = "fill",
        exclusive_zone = "ignore",
        visible = open,
        reset_on_close = { pending }, -- a reopened menu never starts armed
        child = rect {
            width = "fill",
            height = "fill",
            background = "#11111bcc",
            opacity = 1, -- `from` needs the property set
            animate = { opacity = { duration = 150, from = 0 } },
            children = {
                rect { width = "fill", height = "fill", on_click = close }, -- outside click
                row { align_h = "center", align_v = "center", spacing = 16, children = buttons },
            },
        },
    },
}

How it works

• process.detach runs systemctl and the compositor’s quit command as programs that outlive the shell, so a shutdown is never cut short by the shell exiting (process.detach).
• Log out branches on mantle.workspaces’ compositor field (workspaces).
• Lock goes through the lock capability, which needs a declared lock screen (lock screen, lock).
• reset_on_close = { pending } disarms the menu whenever it closes, whether a click, a run action or mantle toggle closed it (reset on close).
• One named state, pending, holds the armed action; a second click on the same button runs it (named state).
• A full-size rect under the row closes the menu; the row is declared after it, so it is on top (close an overlay).
• hover drives the tint and a scale tween, which does not re-lay out the row (hover, animation).

Variations

Notification popups

Notification cards stacked in the top-right corner, newest first. Each card shows the app, the summary, the formatted body and the sender’s action buttons; clicking it runs the default action, the × dismisses it, and hovering the stack pauses every countdown.

local MAX_CARDS = 4
local stack_hover = hover("notification_stack")

-- Cards to show: not expired, not silenced by do-not-disturb, newest first.
local cards = mantle.notifications:map(function(notifications)
    local out = {}
    for _, item in ipairs(notifications.feed) do
        local quiet = notifications.dnd and item.urgency ~= "critical"
        if not item.expired and not quiet and #out < MAX_CARDS then
            out[#out + 1] = item
        end
    end
    return out
end)

-- A text span is a text run as it is; links also get a colour. Image spans are skipped.
local function body_runs(spans)
    local runs = {}
    for _, span in ipairs(spans) do
        if span.kind == "text" then
            -- A copy: the span belongs to the pushed snapshot every other reader shares.
            local run = {}
            for field, value in pairs(span) do run[field] = value end
            if run.href then
                run.underline, run.color = true, "#89b4fa"
            end
            runs[#runs + 1] = run
        end
    end
    return runs
end

local function artwork(item)
    if item.image_path then
        return rect {
            width = 40,
            height = 40,
            radius = 8,
            clip = "rounded",
            children = { image { source = item.image_path, fit = "cover", width = "fill", height = "fill" } },
        }
    end
    return icon { name = item.app_icon or "dialog-information-symbolic", size = 32 }
end

local function action_buttons(item)
    local buttons = {}
    for index, action in ipairs(item.actions) do
        buttons[index] = rect {
            width = "fill",
            padding = 6,
            radius = 6,
            background = "#313244",
            on_click = function() mantle.notifications:invoke_action(item.id, action.key) end,
            children = {
                text { content = action.label, align_h = "center", elide = "end", foreground = "#cdd6f4" },
            },
        }
    end
    return row { width = "fill", spacing = 6, visible = #buttons > 0, children = buttons }
end

local function card(item)
    local critical = item.urgency == "critical"
    local runs = body_runs(item.body)
    return row {
        width = "fill",
        padding = 12,
        radius = 12,
        background = "#1e1e2ef2",
        border_width = 1,
        border_color = critical and "#f38ba8" or "#45475a",
        opacity = 1, -- `from` needs the property set
        scale = 1,
        animate = {
            opacity = { duration = 150, from = 0 },
            -- Grows in place: a slide would leave the surface and be clipped at its edge.
            scale = { duration = 200, easing = "out_cubic", from = 0.95 },
            move = { duration = 200, easing = "out_cubic" }, -- older cards slide down for a new one
            exit = { duration = 150, opacity = 0 },
        },
        on_click = function()
            if item.has_default_action then
                mantle.notifications:invoke_action(item.id, "default")
            else
                mantle.notifications:dismiss(item.id)
            end
        end,
        spacing = 10,
        children = {
            artwork(item),
            column {
                width = "fill",
                spacing = 4,
                children = {
                    row {
                        width = "fill",
                        spacing = 6,
                        children = {
                            text { content = item.app_name, width = "fill", elide = "end", font_size = 11, foreground = "#a6adc8" },
                            rect {
                                padding = { left = 4, right = 4 },
                                radius = 4,
                                on_click = function() mantle.notifications:dismiss(item.id) end,
                                children = { text { content = "×", font_size = 14, foreground = "#a6adc8" } },
                            },
                        },
                    },
                    text {
                        content = { { text = item.summary, bold = true } },
                        width = "fill",
                        elide = "end",
                        font_size = 13,
                        foreground = "#cdd6f4",
                    },
                    text {
                        content = runs,
                        visible = #runs > 0,
                        width = "fill",
                        wrap = "word",
                        max_lines = 4,
                        elide = "end",
                        foreground = "#bac2de",
                        on_link = function(href) mantle.applications:open_url(href) end,
                    },
                    action_buttons(item),
                },
            },
        },
    }
end

return {
    panel {
        id = "notifications",
        layer = "overlay",
        anchor = { top = true, right = true },
        margin = { top = 8, right = 8 },
        width = 380,
        visible = cards:map(function(shown) return #shown > 0 end),
        child = column {
            width = "fill",
            hover = stack_hover,
            -- Pause every countdown while the pointer is over the stack.
            on_hover = function(inside) mantle.notifications:hold_expiry(inside and 300 or 0) end,
            children = {
                list {
                    width = "fill",
                    spacing = 8,
                    items = cards,
                    key = function(item) return tostring(item.id) end,
                    each = card,
                },
            },
        },
    },
}

How it works

• feed is the newest 20, expired ones included; the map keeps the live ones and caps them (notifications).
• dnd only mutes sounds, so hiding popups during it is the config’s filter; critical ones still show.
• key by id keeps each card’s node when a newer one arrives above it, so only the new one animates in while animate.move slides the older ones down; a dismissed card fades out through animate.exit, except the last one, which leaves with its hidden panel (identity, move, exit).
• A body’s text spans pass to text as runs unchanged; on_link hands a clicked href to open_url (text runs, applications).
• The × is a clickable rect inside the clickable card: the innermost one with a handler takes the click (pointer).
• on_hover on the stack calls hold_expiry, so a card cannot expire while being read; the hold lapses after 300 s of continuous hover (hover).
• The panel is anchored to two edges, so it measures its content and grows with the stack (corner stack).

Variations

App launcher

A centred search overlay for installed apps. Typing ranks desktop entries with fzf’s scorer, the arrow keys move the selection, Enter or a click launches, Escape clears the query, then closes on a second press, and a click outside closes it. Open it from a compositor keybind with mantle toggle launcher_open.

local MAX_RESULTS = 50

local open = state("launcher_open", false)
local query = state("launcher_query", "")
local selected = state("launcher_selected", 1)
local results_scroll = scroll("launcher_results")

local function close()
    open:set(false)
end

-- Best score of the name, generic name and keywords; nil when none match.
local function score_of(entry, needle)
    local best, best_start = fuzzy(entry.name, needle)
    for _, field in ipairs({ entry.generic_name or "", table.concat(entry.keywords, " ") }) do
        local score, start = fuzzy(field, needle)
        if score and (best == nil or score > best) then
            best, best_start = score, start
        end
    end
    return best, best_start
end

local matches = computed({ mantle.applications, query }, function(applications, needle)
    local scored = {}
    for _, entry in ipairs(applications.entries) do
        local score, start = score_of(entry, needle)
        if not entry.no_display and score then
            scored[#scored + 1] = { entry = entry, score = score, start = start }
        end
    end
    table.sort(scored, function(left, right)
        if left.score ~= right.score then return left.score > right.score end
        if left.start ~= right.start then return left.start < right.start end
        return left.entry.id < right.entry.id -- unique, so the order is stable
    end)
    local out = {}
    for index = 1, math.min(#scored, MAX_RESULTS) do
        out[index] = scored[index].entry
    end
    return out
end, {})

local function launch(entry)
    if entry then
        mantle.applications:launch(entry.id)
    end
    close()
end

local function move(step)
    local count = #matches:get()
    if count == 0 then
        return
    end
    selected:set((selected:get() - 1 + step) % count + 1) -- wraps at both ends
    results_scroll:reveal(selected:get())
end

local search = rect {
    width = "fill",
    padding = { left = 12, right = 12 },
    radius = 10,
    background = "#313244",
    children = {
        textfield {
            id = "search",
            width = "fill",
            height = 40,
            font_size = 16,
            foreground = "#cdd6f4",
            placeholder = "Search apps",
            autofocus = true,
            on_change = function(text)
                query:set(text)
                selected:set(1)
                results_scroll:reveal(1)
            end,
            on_key = function(key)
                if key.name == "Down" or key.name == "Tab" then move(1) end
                if key.name == "Up" or key.name == "ISO_Left_Tab" then move(-1) end
            end,
            on_submit = function() launch(matches:get()[selected:get()]) end,
            on_cancel = function(cleared)
                if not cleared then close() end -- first Escape clears, second closes
            end,
        },
    },
}

local results = list {
    width = "fill",
    max_height = 400,
    spacing = 2,
    scroll = results_scroll,
    items = matches,
    key = function(entry) return entry.id end,
    each = function(entry)
        return row {
            width = "fill",
            padding = 8,
            radius = 8,
            -- Per row, so a move reruns this and builds no row.
            background = computed({ matches, selected }, function(entries, current)
                local picked = entries[current]
                return picked and picked.id == entry.id and "#45475a" or "#00000000"
            end),
            on_click = function() launch(entry) end,
            spacing = 12,
            children = {
                icon { name = entry.icon or "application-x-executable", size = 32, align_v = "center" },
                column {
                    width = "fill",
                    align_v = "center",
                    children = {
                        text { content = entry.name, width = "fill", elide = "end", font_size = 14, foreground = "#cdd6f4" },
                        text {
                            content = entry.comment or entry.generic_name or "",
                            visible = (entry.comment or entry.generic_name) ~= nil,
                            width = "fill",
                            elide = "end",
                            font_size = 11,
                            foreground = "#a6adc8",
                        },
                    },
                },
            },
        }
    end,
}

return {
    panel {
        id = "launcher",
        layer = "overlay",
        output = "active",
        anchor = { top = true, bottom = true, left = true, right = true },
        width = "fill",
        height = "fill",
        exclusive_zone = "ignore",
        visible = open,
        reset_on_close = { query, selected, results_scroll }, -- however it closed, it reopens fresh
        keyboard_interactivity = "exclusive", -- hiding destroys the surface, so no binding needed
        child = rect {
            width = "fill",
            height = "fill",
            background = "#11111b80",
            children = {
                -- Catches clicks outside the card.
                rect { width = "fill", height = "fill", on_click = close },
                column {
                    width = 560,
                    align_h = "center",
                    margin = { top = 160 },
                    padding = 12,
                    spacing = 8,
                    radius = 16,
                    background = "#1e1e2e",
                    border_width = 1,
                    border_color = "#45475a",
                    children = {
                        search,
                        results,
                        text {
                            content = "No matches",
                            visible = matches:map(function(entries) return #entries == 0 end),
                            align_h = "center",
                            padding = 12,
                            foreground = "#6c7086",
                        },
                    },
                },
            },
        },
    },
}

Bind a key to mantle toggle launcher_open, for example bind = SUPER, Space, exec, mantle toggle launcher_open on Hyprland or Mod+Space { spawn "mantle" "toggle" "launcher_open"; } on niri.

How it works

• applications.entries includes desktop entries used for window icon lookup; the launcher omits entries with no_display = true. It follows installs and removals; launch takes an entry’s id and runs it detached (applications).
• fuzzy scores one candidate; ranking, the tiebreak and the cap stay in Lua (fuzzy).
• computed joins the capability with the query (derived signals).
• Each row derives its own highlight from matches and selected. An arrow key reruns those 50 small functions and builds no row; folding the selection into items would call each for all 50 on every keypress (when items rebuild).
• The textfield owns the typed text and reports it through on_change; on_key gets the arrow and Tab keys the field does not use (textfield, key handlers).
• scroll(name):reveal(index) keeps the selected row in view inside the max_height list (scroll, list).
• reset_on_close returns the query, the selection and the scroll to their start whenever the launcher closes, including by mantle toggle (reset on close).
• "exclusive" hands the panel the keyboard when it maps, and autofocus gives it to the field (keyboard focus).
• A full-size transparent rect under the card closes it on an outside click (close an overlay).

Variations

System tray with menu

Tray icons in the bar. A left click activates the app (or opens the menu of a menu-only item), a middle click sends its secondary action, the wheel scrolls it and a right click opens its menu in a dropdown. Submenus expand in place, check marks and radio dots follow the app, and disabled entries are drawn greyed out.

local menu_open = state("tray_menu_open", false)
local menu_anchor = state("tray_menu_anchor", { x = 0, y = 0, width = 1, height = 1 })
local menu_item = state("tray_menu_item", "") -- the tray item whose menu is open
local expanded = state("tray_menu_expanded", {}) -- open submenu ids, as strings

local function close_menu()
    menu_open:set(false)
end

local function open_menu(item, rect)
    menu_item:set(item.id)
    expanded:set({})
    menu_anchor:set(rect)
    menu_open:set(true)
    mantle.tray:menu_will_show(item.id, 0)
end

local function artwork(item)
    local name = item.icon_name
    local path = item.icon_path
    if item.status == "needs_attention" and (item.attention_icon_name or item.attention_icon_path) then
        name, path = item.attention_icon_name, item.attention_icon_path
    end
    if path then
        return image { source = path, width = 16, height = 16, fit = "contain", align_v = "center" }
    end
    -- `foreground` tints symbolic icons, which are dark by default; colour icons ignore it.
    return icon { name = name or "application-x-executable", size = 16, foreground = "#cdd6f4", align_v = "center" }
end

local tray_items = list {
    direction = "horizontal",
    spacing = 2,
    align_v = "center",
    items = mantle.tray:map(function(tray)
        local shown = {}
        for _, item in ipairs(tray.items) do
            if item.status ~= "passive" then -- passive asks to be hidden
                shown[#shown + 1] = item
            end
        end
        return shown
    end),
    key = function(item) return item.id end,
    each = function(item)
        local wheel = 0 -- partial notches from a touchpad or high-resolution wheel
        return rect {
            padding = 4,
            radius = 6,
            on_click = function(rect, which)
                local cx = math.floor(rect.x + rect.width / 2)
                local cy = math.floor(rect.y + rect.height)
                if item.menu and (which == "right" or which == "left" and item.item_is_menu) then
                    open_menu(item, rect)
                elseif which == "right" then
                    mantle.tray:context_menu(item.id, cx, cy)
                elseif which == "left" then
                    mantle.tray:activate(item.id, cx, cy)
                elseif which == "middle" then
                    mantle.tray:secondary_activate(item.id, cx, cy)
                end
            end,
            on_wheel = function(_, steps)
                wheel = wheel + steps
                local notches = math.modf(wheel) -- whole notches; the fraction carries over
                if notches == 0 then return end
                wheel = wheel - notches
                mantle.tray:scroll(item.id, math.tointeger(notches), "vertical")
            end,
            children = { artwork(item) },
        }
    end,
}

-- The open item's menu as flat rows, depth-first, with open submenus inlined.
local function flatten(entries, depth, open, out)
    for _, entry in ipairs(entries or {}) do
        out[#out + 1] = { entry = entry, depth = depth }
        if #entry.children > 0 and open[tostring(entry.id)] then
            flatten(entry.children, depth + 1, open, out)
        end
    end
    return out
end

local menu_rows = computed({ mantle.tray, menu_item, expanded }, function(tray, id, open)
    for _, item in ipairs(tray.items) do
        if item.id == id then
            return flatten(item.menu, 0, open, {})
        end
    end
    return {}
end, {})

-- "_Quit" -> "Quit"; "__" is a literal underscore.
local function strip_mnemonic(label)
    return ((label or ""):gsub("__", "\0"):gsub("_", ""):gsub("%z", "_"))
end

local function marker(entry)
    if #entry.children > 0 then
        return "›"
    elseif entry.toggle_state == 1 then
        return entry.toggle_type == "radio" and "●" or "✓"
    end
    return ""
end

local function menu_row(row_data)
    local entry = row_data.entry
    local indent = 8 + row_data.depth * 12
    if entry.menu_type == "separator" then
        return rect {
            width = "fill",
            padding = { top = 4, bottom = 4, left = indent, right = 8 },
            children = { rect { width = "fill", height = 1, background = "#45475a" } },
        }
    end
    local mark = marker(entry)
    local row_hover = hover("tray_menu_row_" .. entry.id .. "_" .. row_data.depth)
    return row {
        width = "fill",
        padding = { top = 6, bottom = 6, left = indent, right = 8 },
        radius = 6,
        hover = row_hover,
        background = row_hover:map(function(on) return on and entry.enabled and "#313244" or "#00000000" end),
        opacity = entry.enabled and 1 or 0.4,
        on_click = function()
            if #entry.children > 0 then
                local key = tostring(entry.id)
                local open = {}
                for id, value in pairs(expanded:get()) do open[id] = value end
                open[key] = not open[key] or nil
                expanded:set(open)
                if open[key] then
                    mantle.tray:menu_will_show(menu_item:get(), entry.id)
                end
            elseif entry.enabled then
                mantle.tray:activate_menu_item(menu_item:get(), entry.id)
                close_menu()
            end
        end,
        spacing = 8,
        children = {
            icon { name = entry.icon_name or "", size = 14, foreground = "#cdd6f4", visible = entry.icon_name ~= nil, align_v = "center" },
            text { content = strip_mnemonic(entry.label), width = "fill", elide = "end", foreground = "#cdd6f4" },
            text { content = mark, visible = mark ~= "", foreground = "#a6adc8" },
        },
    }
end

return {
    panel {
        id = "bar",
        layer = "top",
        anchor = { top = true, left = true, right = true },
        width = "fill",
        height = 32,
        exclusive_zone = true,
        child = row {
            width = "fill",
            height = "fill",
            padding = { left = 8, right = 8 },
            background = "#1e1e2e",
            children = { rect { width = "fill" }, tray_items },
        },
    },
    popup {
        id = "tray_menu",
        parent = "bar",
        anchor_rect = menu_anchor,
        anchor = "bottom",
        gravity = "bottom_left",
        offset = { y = 4 },
        constraint_adjustment = { "slide_x", "flip_y" },
        visible = menu_open,
        on_dismiss = close_menu,
        width = 260,
        padding = 6,
        radius = 10,
        background = "#1e1e2e",
        border_width = 1,
        border_color = "#45475a",
        child = list {
            width = "fill",
            max_height = 480,
            scroll = scroll("tray_menu"),
            items = menu_rows,
            -- The same entry at two depths is two rows.
            key = function(row_data) return row_data.entry.id .. ":" .. row_data.depth end,
            each = menu_row,
        },
    },
}

How it works

• tray.items arrive in registration order with their whole DBusMenu tree in menu (tray).
• on_click gets the button’s rect and the mouse button; the rect goes straight into the popup’s anchor_rect (pointer, popup).
• The popup grabs the pointer, so an outside click dismisses it and on_dismiss clears the state (dismissal).
• menu_will_show notifies apps when a menu opens (id 0) or a submenu expands (entry.id), letting apps that build items lazily populate them.
• Right-clicking an item with no DBusMenu calls context_menu at the button’s bottom centre so native menus still appear. The coordinates are the bar’s own: a layer surface cannot learn its screen position, so they match the screen only for a top bar on the output at the screen’s origin.

Variations

Media player

A now-playing pill in the bar for any MPRIS player (Spotify, mpv, a browser tab). Click it for a card with cover art, title, artist, a seekable progress bar and previous, play/pause and next buttons. It prefers whichever player is playing and hides when none runs.

local card_open = state("media_open", false)
local card_anchor = state("media_anchor", { x = 0, y = 0, width = 1, height = 1 })
-- Where `position` was last reported, in `mantle.clock.monotonic` seconds.
local position_mark = state("media_position_mark", { key = "", at = 0 })
local selected_player = state("media_selected_player", "")

-- Prefer a playing player. When all are paused, keep the selected one while it remains registered.
local function pick(mpris)
    local players = mpris.players
    for _, candidate in ipairs(players) do
        if candidate.play_state == "playing" then
            return candidate
        end
    end
    for _, candidate in ipairs(players) do
        if candidate.id == selected_player:get() then
            return candidate
        end
    end
    return players[1]
end

local player = mantle.mpris:map(pick)

mantle.mpris:on_change(function(mpris)
    local players = mpris and mpris.players or {}
    if #players == 0 then
        card_open:set(false) -- so the next player to appear does not reopen the card
    end
    for _, candidate in ipairs(players) do
        if candidate.play_state == "playing" then
            selected_player:set(candidate.id)
            return
        end
    end
    for _, candidate in ipairs(players) do
        if candidate.id == selected_player:get() then
            return
        end
    end
    selected_player:set(players[1] and players[1].id or "")
end)

local function report_key(current)
    return current.id .. ":" .. current.position_updated_at
end

-- Positions are not polled: stamp each new report so the bar can add the time since.
mantle.mpris:on_change(function(mpris)
    local current = pick(mpris)
    if current then
        local key = report_key(current)
        if key ~= position_mark:get().key then
            position_mark:set({ key = key, at = mantle.clock:now() })
        end
    end
end)

-- Live position in microseconds, or nil when unknown. `monotonic` is as of the last tick, up to
-- `interval` behind the `now()` stamp, so the difference is clamped at 0.
local position = computed({ player, position_mark, mantle.clock }, function(current, mark, clock)
    if current == nil or current.position == nil then
        return nil
    end
    local elapsed = 0
    if current.play_state == "playing" and mark.key == report_key(current) then
        elapsed = math.max(0, clock.monotonic - mark.at) * 1000000
    end
    local rate = current.rate or 1
    if rate <= 0 then rate = 1 end
    local now = current.position + elapsed * rate
    return current.length and math.min(now, current.length) or now
end)

local function clock(microseconds)
    local seconds = math.max(0, microseconds // 1000000)
    return string.format("%d:%02d", seconds // 60, seconds % 60)
end

local function control(command)
    local current = player:get()
    if current then
        mantle.mpris:control(current.id, command)
    end
end

local function control_button(glyph, command, size)
    return rect {
        align_v = "center",
        padding = 8,
        radius = 20,
        background = command == "play_pause" and "#89b4fa" or "#313244",
        on_click = function() control(command) end,
        children = { icon { name = glyph, size = size, foreground = command == "play_pause" and "#1e1e2e" or "#cdd6f4" } },
    }
end

local play_glyph = player:map(function(current)
    return current and current.play_state == "playing" and "media-playback-pause-symbolic" or "media-playback-start-symbolic"
end)

local wheel = 0 -- partial notches from a touchpad or high-resolution wheel
local pill = row {
    align_v = "center",
    padding = { left = 10, right = 10, top = 4, bottom = 4 },
    radius = 12,
    background = "#313244",
    visible = player:map(function(current) return current ~= nil end),
    on_click = function(rect, which)
        if which == "middle" then
            control("play_pause")
        else
            card_anchor:set(rect)
            card_open:set(not card_open:get())
        end
    end,
    on_wheel = function(_, steps)
        wheel = wheel + steps
        local notches = math.modf(wheel) -- whole notches; the fraction carries over
        wheel = wheel - notches
        for _ = 1, math.abs(notches) do
            control(notches > 0 and "previous" or "next")
        end
    end,
    spacing = 6,
    children = {
        icon { name = play_glyph, size = 14, foreground = "#cdd6f4", align_v = "center" },
        text {
            max_width = 240,
            elide = "end",
            foreground = "#cdd6f4",
            content = player:map(function(current)
                if current == nil or current.title == "" then return "" end
                return current.artist ~= "" and current.artist .. " — " .. current.title or current.title
            end),
        },
    },
}

local progress = rect {
    width = "fill",
    height = 6,
    radius = 3,
    clip = "rounded",
    background = "#45475a",
    -- Seek on release, to where the pointer let go.
    on_drag = function(rect, pointer, phase)
        local current = player:get()
        if phase == "end" and current and current.length and current.length > 0 then
            local fraction = math.max(0, math.min(1, pointer.x / rect.width))
            mantle.mpris:seek(current.id, math.floor(fraction * current.length))
        end
    end,
    children = {
        rect {
            height = "fill",
            background = "#89b4fa",
            width = computed({ player, position }, function(current, now)
                if current == nil or not current.length or current.length <= 0 or now == nil then return "0%" end
                return string.format("%.1f%%", now / current.length * 100)
            end),
        },
    },
}

local card = column {
    width = 320,
    padding = 16,
    spacing = 12,
    children = {
        row {
            width = "fill",
            spacing = 12,
            children = {
                rect {
                    width = 64,
                    height = 64,
                    radius = 8,
                    clip = "rounded",
                    background = "#313244",
                    children = {
                        image {
                            width = "fill",
                            height = "fill",
                            fit = "cover",
                            source = player:map(function(current) return current and current.album_art_path or "" end),
                        },
                    },
                },
                column {
                    width = "fill",
                    align_v = "center",
                    spacing = 2,
                    children = {
                        text {
                            content = player:map(function(current) return current and current.title or "" end),
                            width = "fill", elide = "end", font_size = 14, foreground = "#cdd6f4",
                        },
                        text {
                            content = player:map(function(current) return current and current.artist or "" end),
                            width = "fill", elide = "end", foreground = "#a6adc8",
                        },
                        text {
                            content = player:map(function(current) return current and current.identity or "" end),
                            width = "fill", elide = "end", font_size = 11, foreground = "#6c7086",
                        },
                    },
                },
            },
        },
        progress,
        row {
            width = "fill",
            children = {
                text { content = position:map(function(now) return now and clock(now) or "" end), font_size = 11, foreground = "#a6adc8" },
                rect { width = "fill" },
                text {
                    content = player:map(function(current) return current and current.length and clock(current.length) or "" end),
                    font_size = 11,
                    foreground = "#a6adc8",
                },
            },
        },
        row {
            align_h = "center",
            spacing = 12,
            width = "fill",
            children = {
                control_button("media-skip-backward-symbolic", "previous", 16),
                control_button(play_glyph, "play_pause", 20),
                control_button("media-skip-forward-symbolic", "next", 16),
            },
        },
    },
}

return {
    panel {
        id = "bar",
        layer = "top",
        anchor = { top = true, left = true, right = true },
        width = "fill",
        height = 32,
        exclusive_zone = true,
        child = row {
            width = "fill",
            height = "fill",
            padding = { left = 8, right = 8 },
            background = "#1e1e2e",
            children = { rect { width = "fill" }, pill, rect { width = "fill" } },
        },
    },
    popup {
        id = "media_card",
        parent = "bar",
        anchor_rect = card_anchor,
        anchor = "bottom",
        gravity = "bottom",
        offset = { y = 6 },
        visible = computed({ card_open, player }, function(open, current) return open and current ~= nil end),
        on_dismiss = function() card_open:set(false) end,
        radius = 14,
        background = "#1e1e2e",
        border_width = 1,
        border_color = "#45475a",
        child = card,
    },
}

How it works

• players is in registration order; the map prefers one that is playing and keeps it selected while paused (mpris).
• position is a snapshot, not polled. on_change stamps each new report with mantle.clock:now(), and a computed adds the seconds since, from the ticking monotonic field, clamped at 0 (clock, derived signals).
• The fill is a "NN%" width in a rounded, clipped track; on_drag on the track seeks on release (pointer, clip).
• album_art_path is an existing local path or "". A remote cover arrives only as art_url; fetch it into a cache file with curl through process.run and draw that path. An image with source = "" draws nothing over the placeholder rect (image).
• The card is a grabbing popup anchored to the pill’s click rect; it also closes when the last player quits.

Variations

Component libraries

Mantle ships nodes, not widgets. These libraries build full widget sets from them in plain Lua on the public API, each with a demo app that shows every component. Both are MIT-licensed and typed for LuaLS, so the editor completes and checks every opts table.

To use one, copy or symlink its module folder (glass/ or m3/) into your config directory and require it. To run its demo, clone the repository and run mantle -c . inside it.

mantle-glass

A Liquid Glass component library: window chrome (traffic lights, toolbars, sidebar, inspector, tabs), controls, text fields, pickers, tables and outlines, menus, popovers, alerts, sheets, a menu bar and a Dock. Its glass materials refract and follow the desktop’s dark mode, accent, contrast and reduced-motion settings.

fonts { "Inter", "lucide", "Noto Sans" }
local glass = require("glass")
glass.core.window = "app" -- the app window's id, before building controls

return {
    glass.app_window {
        id = "app",
        title = "My app",
        child = glass.button("save", { label = "Save", kind = "default" }),
    },
}

mantle-material

A Material 3 Expressive component library: the full M3 catalogue (actions, communication, containment, navigation, selection and text inputs), dynamic colour from one seed, the Expressive motion springs, and adaptive layouts: window size classes, navigation that becomes a bar, rail or drawer by width, and list-detail panes.

fonts { "Roboto", "Noto Sans" }
local m3 = require("m3")
m3.theme.seed:set("#6750A4") -- optional

return {
    m3.app_window {
        id = "app",
        title = "My app",
        child = m3.button("save", { label = "Save", on_click = function() m3.overlay.notify("Saved") end }),
    },
}

Runtime

What runs a config: the Lua VM and its libraries, how require finds modules, what a reload re-runs and what it keeps, and the limits the engine enforces. Read it before splitting a config into modules, when a reload does something unexpected, or when a log line names a budget.

Only shell.lua is required. This layout puts the bar in bar.lua and its clock in widgets/clock.lua:

-- shell.lua
local bar = require("bar")
return { bar }

-- bar.lua
local clock = require("widgets.clock") -- widgets/clock.lua

return panel {
    id = "bar",
    layer = "top",
    anchor = { top = true, left = true, right = true },
    height = 32,
    background = "#1e1e2eff",
    child = row { padding = 8, children = { clock } },
}

-- widgets/clock.lua
return text {
    content = mantle.clock:map(function(clock)
        return os.date("%H:%M", clock.time)
    end, ""), -- "" until the first push
    foreground = "#cdd6f4ff",
}

Saving any of the three re-runs shell.lua in place, and the edited module is loaded fresh.

The VM

Mantle runs as two processes (glossary). The Supervisor is the mantle process: it owns the backends, watches the config and restarts the other one. The Renderer holds the Lua VM, the scene and the Wayland connection, all on one thread. There is one Lua 5.4 VM per generation. Anything that blocks it freezes every surface on every monitor, so the blocking parts of the standard library are removed (ADR-0048).

load accepts text and precompiled chunks. Use require for Lua files in the config directory. dofile and loadfile are unavailable because they read files on the render thread. To read other files, use process.run or persistent_table for JSON. To run a program, use process.run. For os.difftime(a, b), write a - b.

The engine adds these globals. Every module sees the same ones.

Modules and require

The config is a directory, not a file. shell.lua is the entry, and require resolves module names inside that directory only.

Bind every module to a local before listing it, or the file path becomes a surface:

return { require("bar") }        -- { bar, "/home/me/.config/mantle/bar.lua" }: fails
local bar = require("bar")
return { bar }                   -- works

The failure reads surface 2 is a string, not a node, followed by this hint. Parentheses, (require("bar")), also truncate to one value.

Evaluation, reload and generations

shell.lua returns a surface (panel, window, popup or lock), an array of them, {}, or nothing. Running it top to bottom is one evaluation. The engine runs it at startup and again on every reload.

What triggers a reload:

The watcher follows the config path resolved at startup. Retargeting a symlink later changes nothing until a restart.

How each failure ends:

An error from an engine function, a method on an engine object (signal:reveal, mantle.idle:register_threshold) or a capability action keeps its leading file:line: through pcall. Only an unknown capability field omits it there; the logged and mantle check forms carry it.

A failed reload keeps the old scene, but not the old evaluation’s actions, timers, on_change handlers or idle thresholds (what survives):

Fix and save to get them back.

mantle.rescue clears when a reload applies. A rescue from a failed live update or startup apply also clears when a later pass over the same scene applies. A config can draw its own error banner:

local rescue = mantle.rescue

return panel {
    id = "rescue",
    layer = "overlay",
    anchor = { bottom = true, left = true, right = true },
    visible = rescue:map(function(state) return state.is_rescue end),
    background = "#f38ba8ff",
    padding = 8,
    child = text {
        content = rescue:map(function(state) return state.error_log end),
        foreground = "#11111bff",
    },
}

What survives a reload

Top-level side effects run again on every reload. A top-level timer chain or long-running process.run is restarted, not doubled, because the old ones are cleared first. To keep a program running through a save, declare it with session_process (processes).

Limits and budgets

Config Lua and the renderer share one thread, so the engine bounds how long config code can hold it.

Not budgeted: an evaluation’s top level, input handlers (on_click, on_drag, on_wheel, on_hover, on_link, textfield callbacks, on_close_request, on_dismiss), process.run callbacks, palette callbacks and idle callbacks. A slow one stalls every surface until it returns.

Keep maps cheap. Build lookup tables once at the top level, which has no budget, and do only an index and a format inside the map:

-- Evaluation has no CPU budget: build lookup tables here, once.
local levels = { "empty", "low", "half", "high", "full" }

-- The map runs on every push, well under the 2.5 ms frame target: one check, one index, one format.
local battery_label = mantle.battery:map(function(battery)
    if not battery.present then
        return "" -- no battery on a desktop
    end
    local level = levels[math.min(#levels, battery.percent // 20 + 1)]
    return string.format("%s %d%%", level, battery.percent)
end, "")

Work that is slow by nature (parsing a large file, searching many entries) belongs in a program started with process.run, whose output callback sets a state.

Output and logging

Both streams land in the shell’s log file. Read it with mantle log. A terminal that started mantle in the foreground also gets a copy.

How do I…

Find out why a reload did nothing

Share values between modules

A module runs once per evaluation, and every later require of it returns the same table. For a value that changes, use a named state: the same name gives the same signal in any module.

-- lib/palette.lua: every module that requires it in one evaluation gets this same table.
return {
    accent = "#89b4faff",
    surface = "#1e1e2eff",
    dnd = state("dnd", false), -- named state: one signal per name, from any module
}

-- shell.lua
local palette = require("lib.palette")

return panel {
    id = "bar",
    layer = "top",
    anchor = { top = true, left = true, right = true },
    height = 32,
    background = palette.surface,
    child = text {
        content = palette.dnd:map(function(on) return on and "silent" or "" end),
        foreground = palette.accent,
    },
}

Run something once, not on every reload

Globals survive a reload, so a global guard runs once per Renderer start:

-- A global lives in the VM: it survives reloads and resets when the Renderer restarts.
if not started_at then
    started_at = os.time()
    log.info("renderer started")
end

return panel {
    id = "bar",
    layer = "top",
    anchor = { top = true, left = true, right = true },
    height = 32,
    child = text { content = "up since " .. os.date("%H:%M", started_at) },
}

Timers and actions cannot be guarded this way, because every reload clears them. Declare them at the top level every time.

Gotchas

See also: cli · signals · processes · scripting · capabilities · surfaces · glossary for generation, Supervisor and Renderer.

Source: VM setup and require, reload, apply, watcher, budget, scalar checks, property ranges, respawn, respawn brake.

Signals

A config builds its node tree once; signals change it afterwards. Any node or surface property can hold a signal in place of a plain value. The engine reads the signal while it lays out, and a write to it re-resolves only the surfaces that read it.

The one rule

A property that holds a signal stays live. A property that holds a plain value, including whatever :get() returned, keeps that value until the next reload.

local minute = state("minute", 45)
local clock = minute:map(function(value) return string.format("12:%02d", value) end)

local function reading(label, value)
  return column { spacing = 2, children = {
    text { content = label, font_size = 12, foreground = "#a6adc8" },
    text { content = value, font_size = 20, font_weight = 700, foreground = "#cdd6f4" },
  } }
end

return row {
  spacing = 20,
  padding = 14,
  radius = 12,
  background = "#1e1e2e",
  children = {
    rect {
      padding = { left = 12, right = 12, top = 8, bottom = 8 },
      radius = 8,
      align_v = "center",
      background = "#89b4fa",
      on_click = function() minute:set(minute:get() + 1) end,
      children = { text { content = "Next minute", font_weight = 700, foreground = "#1e1e2e" } },
    },
    reading("Live", clock),
    reading("Snapshot", string.format("12:%02d", minute:get())),
  },
}

Click Next minute to update only the Live column. The screenshot captures that first click.

A capability (mantle.<name>, see capabilities) is a signal too. When a signal resolves to nil, its property counts as absent and takes the property’s default.

For values your config writes, start with named state. To transform or combine live values, use derived signals. The full API and error messages are in the reference.

Capabilities before their first push

A capability reads nil until its first snapshot arrives (hydration), and in mantle check’s first pass. lock and polkit push their idle state at startup; after a restart while locked, lock stays nil until the lock is taken again. :map(fn, before?) and computed(deps, fn, before?) skip fn and hold before until every capability dependency has pushed. Set before to what a guard would have returned ({}, 0, "", false); without it the signal reads nil. :get() and on_change’s previous still see nil.

Named state

state(name, initial) is the config’s own writable value. Its identity is its name. Every call with the same name returns the same signal, from any module and across reloads.

local open = state("details_open", false)

column { children = {
  rect {
    on_click = function() open:set(not open:get()) end,
    children = { text { content = "Details" } },
  },
  text { content = "More information", visible = open },
} }

The click writes open; visible = open reads it again. visible = open:get() would take only a snapshot.

on_change: react to a write

s:on_change(fn) runs fn(current, previous) after a write changes the state, whoever wrote it: a click, a timer, another handler, or mantle set/mantle toggle from outside the shell. Use it for an effect that must follow the state however it changed, such as another surface’s state or a command.

local mode = state("mode", "balanced")
local last = state("last_mode", "balanced")

-- `mantle set mode '"performance"'` from a keybind runs this too.
mode:on_change(function(_, previous) last:set(previous) end)

return rect {
  on_click = function() mode:set(last:get()) end,
  children = { text { content = last:map(function(m) return "Back to " .. m end) } },
}

Derived signals (:map, computed, delay, pulse) have no name. Each evaluation builds them fresh, so a reload drops a pending delay and closes an open pulse window. See runtime for everything else a reload keeps.

Derived signals

Use :map(fn) to turn one signal’s value into another value. Use computed({ a, b }, fn) when the result needs several signals. Both return a signal you can bind to a property. Their functions should only calculate a value: write state or run commands from on_click, an on_change or a timer. The functions run under the CPU budget.

A derived colour:

local battery_color = mantle.battery:map(function(battery)
  if not battery.present then return "#6c7086" end
  return battery.percent <= 20 and "#f38ba8" or "#a6e3a1"
end, "#6c7086")

text { content = "●", foreground = battery_color }

Use computed to combine two sources, here a capability and a state that a click toggles:

local show_seconds = state("show_seconds", false)

local clock = computed({ mantle.clock, show_seconds }, function(system, seconds)
  return os.date(seconds and "%H:%M:%S" or "%H:%M", system.time)
end, "")

rect {
  on_click = function() show_seconds:set(not show_seconds:get()) end,
  children = { text { content = clock } },
}

A dropdown under a button is a popup bound to a state the click toggles: dismissal.

delay: hold a value

delay answers the old value until the new one has held for ms. That makes it a trailing debounce, and also a close-hold. OR-ing a signal with its delayed copy keeps a surface mapped for ms after it closes, long enough for an exit fade to play. Hiding a surface or node plays no exit animation of its own (animation).

local open = state("menu_open", false)
local mapped = computed({ open, delay(open, 150) }, function(now, was) return now or was end)

local menu = popup {
  id = "menu", parent = "bar", anchor_rect = { x = 0, y = 0, width = 60, height = 28 },
  anchor = "bottom", gravity = "bottom",
  visible = mapped, -- stays mapped 150 ms after `open` goes false
  on_dismiss = function() open:set(false) end,
  child = column {
    padding = 8, background = "#1e1e2e",
    opacity = open:map(function(is_open) return is_open and 1 or 0 end), -- fades out while held
    animate = { opacity = { duration = 150, from = 0 } },
    children = { text { content = "Settings" } },
  },
}

pulse: mark a change

pulse reports that a change just happened. Use it to fire a one-shot flash or a keyframe animation, which a config cannot restart any other way (animation):

local count = state("count", 0)
local flash = pulse(count, 300) -- true for 300 ms after each change

rect {
  padding = 6,
  background = flash:map(function(on) return on and "#f9e2af" or "#313244" end),
  animate = { background = 300 },
  on_click = function() count:set(count:get() + 1) end,
  children = { text { content = count:map(tostring) } },
}

To fire on only one edge, combine the pulse with its source: computed({ pulse(plugged, 400), plugged }, function(fired, on) return fired and on end).

geometry: read a node’s laid-out rect

Layout writes the rect after it solves. A change triggers one follow-up pass over the surfaces that read the rect, and never two passes in a row, so a binding that feeds its own measurement cannot loop.

local track = geometry("track")

column { width = 200, children = {
  rect { geometry = track, width = "fill", height = 4, background = "#45475a" },
  text { content = track:map(function(rect) return string.format("%d px wide", math.floor(rect.width)) end) },
} }

elided: read text truncation

Bind elided(name) as a text node’s elided property. It starts false; after layout it is true when elide removes content or max_lines drops wrapped lines, including without an ellipsis. Wrapping alone, box or ancestor clipping, scrolling and occlusion do not count.

The result follows the shaped text, styled runs, font metrics and available width. Content changes, resizing and layout animations recompute it. A changed result schedules one follow-up pass over its readers, sharing geometry’s limit of one follow-up. Failed layouts keep the previous result. The property itself writes the signal and does not count as a reader.

Names persist across reloads. If several texts or output instances bind the same name, it is true when any visible binding is truncated. Hidden, leaving and removed bindings do not contribute; with no visible binding it becomes false.

Keep the expander visible while expanded so that restoring all lines does not remove the collapse button:

local clipped = elided("body")
local expanded = state("body_expanded", false)

return column { width = 240, children = {
    text { width = "fill", wrap = "word", elide = "end", elided = clipped,
        max_lines = expanded:map(function(open) return open and 0 or 2 end),
        content = "A longer message can wrap across several lines. Expand it to read the rest, then collapse it again." },
    rect {
        visible = computed({ expanded, clipped }, function(open, cut) return open or cut end),
        on_click = function() expanded:set(not expanded:get()) end,
        children = { text { content = expanded:map(function(open) return open and "Less" or "More" end) } },
    },
} }

image_status: read an image’s load

Bind image_status(name) as an image’s status. Two shown images on one name in one surface instance fail the pass, naming both. Across instances, such as a surface shown on several outputs, the name follows the first shown image by instance id (bar@DP-1 before bar@HDMI-A-1) whose state is known, else the first one. The value follows that image’s current source:

An inline image (async = false) decodes in the frame that draws it, so "loading" lasts until that frame and moves to "ready" or "failed". A hidden image keeps its last status. Each change schedules one follow-up pass over the signal’s readers, as geometry does.

Fade a picture in once it has decoded:

local load = image_status("cover")

return image {
    width = 160, height = 90, async = true, status = load,
    source = "/usr/share/backgrounds/a.jpg",
    opacity = load:map(function(s) return s.state == "ready" and 1 or 0 end),
    animate = { opacity = 200 },
}

How re-resolution works

While a surface instance (one surface on one output) resolves, the engine records every signal it reads, including reads inside :map and computed bodies. A write marks the written signal dirty, and the next pass re-resolves only the instances that read it.

Readers of a :map or computed result update only when the result changes. Scalars and plain data tables compare by value. A table holding a function, signal or metatable counts as changed on every run; comparison also stops after 256 table entries. For example, an HH:MM label mapped from a per-second clock push updates once a minute. Within one pass, several properties reading the same derived signal calculate it once.

A node reads its children or child table once and keeps what it read while it holds that same table. A node table or children array changed in place is not seen; a signal answering a new table is.

What a node reads again

Within a re-resolved surface, each node keeps the properties it resolved last time until a signal that resolve read is written. A clock written every second resolves its one text again, not the whole bar. A list keeps its items the same way (when items rebuild).

The engine sees signal reads only. A map, computed, each, key or function child must answer from its arguments and the signals it reads; anything else it reads is taken as it was at the node’s last resolve:

A visible = false node’s subtree is frozen. Its children keep their nodes, ids, properties and last geometry. None of their signals is read, no list item function runs and nothing re-lays out until the node is shown again. Signals that only a hidden subtree reads therefore trigger nothing.

Switching views

visible = false keeps a subtree in the tree, frozen: right for a section shown and hidden in place. For views that replace each other, bind the parent’s children to a signal that returns only the current view. The old view leaves the tree, playing its animate.exit, and the new one builds fresh. Give each view its own id: switching views with ids.

Reference

delay and pulse take ms in [1, 60000] rounded to whole milliseconds, and raise outside that range. Both compare values with ==, so a table value (every capability payload, for example) counts as a new value on every push.

Who writes each kind

Only state can be written from Lua. :set on any other kind raises an error that names the kind. :reveal, :scroll_to and :scroll_by work only on a scroll signal.

:set refuses the scalars outside the engine’s value limits and leaves tables unchecked. It checks no types: state("x", 1):set({}) succeeds, and only LuaLS flags it. A :set of what the state already holds changes nothing: 1 over 1 is skipped, 1.0 over 1 is a write. A fresh plain-data table (no metatable, only scalars and such tables inside, 256 entries in all) equal entry for entry is skipped too; the same table written again after changing it in place is a write.

Errors

How do I…

Derive from two capabilities

List every source in computed; before here is "..." (why).

local status = computed({ mantle.network, mantle.audio }, function(network, audio)
  local net = network.connected and "online" or "offline"
  local sink = audio.sinks[1]
  for _, each in ipairs(audio.sinks) do
    if each.active then sink = each end
  end
  local sound = not sink and "no output"
    or sink.muted and "muted" or string.format("%d%%", math.floor(sink.volume or 0))
  return net .. " / " .. sound
end, "...")

text { content = status }

Debounce a search

The field writes every keystroke to a state. The filter reads a delay of that state, so the filter runs once typing pauses for 250 ms.

local query = state("search_query", "")
local settled = delay(query, 250)

local results = settled:map(function(needle)
  local found = {}
  for _, name in ipairs({ "Firefox", "Files", "Terminal", "Settings" }) do
    if needle ~= "" and name:lower():find(needle:lower(), 1, true) then
      found[#found + 1] = text { id = name, content = name }
    end
  end
  return found
end)

column { width = 240, spacing = 4, children = {
  textfield { width = "fill", height = 28, placeholder = "Search", on_change = function(text) query:set(text) end },
  column { spacing = 2, children = results },
} }

Drive UI from a keybind

Bind the surface’s visible to a named state. A compositor keybind that runs mantle toggle launcher_open flips it, and mantle set launcher_open false closes it. Example and compositor syntax: cli. For a keybind that runs Lua code, use action.

Gotchas

See also: runtime (budgets, reload), capabilities, input (hover, scroll), animation, cli, glossary (generation, hydration).

Source: signal core, globals, read tracking, re-resolve, property resolution, kept nodes, frozen subtrees.

Surfaces

A surface is a top-level Wayland object that holds one node tree. shell.lua returns one surface or a list of them, and every other node lives under some surface’s child. This page holds the rules all four roles share; each role has its own page.

An instance is one mapped copy of a declared surface; its id keys the retained scene and names the surface in mantle log (glossary).

A 32 px bar on every output that pushes windows down by its height and prints the output’s connector name:

local bar = panel {
    id = "bar",
    layer = "top",
    anchor = { top = true, left = true, right = true },
    height = 32,
    exclusive_zone = true,
    child = function(output)
        return row {
            width = "fill",
            height = "fill",
            padding = { left = 8, right = 8 },
            background = "#1e1e2e",
            children = {
                rect {
                    align_v = "center",
                    padding = { left = 10, right = 10, top = 3, bottom = 3 },
                    radius = 10,
                    background = "#313244",
                    children = { text { content = output, font_weight = 700, foreground = "#89b4fa" } },
                },
            },
        }
    end,
}

return { bar }

Properties every role takes

Every surface takes id (required), one child node and, except lock, visible; each role’s page has their table. The root is itself a box node, so it also takes the common and box node properties, except those that place a node in a parent (below): its own background, radius, padding, border_*, paint and animate. Any other key is refused, and the error names the closest accepted one or, with none close, lists them all.

The surface root

The root has no parent, so a few node properties mean something else on it:

Reload and structural fields

The returned list is re-read on every reload. Each surface is matched to the last evaluation by its fingerprint, the fields that the protocol fixes when the object is created.

Per-output child

child = function(output) is for panel and lock, the roles with one instance per output. It runs with that instance’s connector name ("DP-1") on the first pass, and again only when the surface root resolves again: a signal the function or the root’s own properties read is written, or a reload (what a node reads again). Bind signals to properties inside it rather than reading them with :get(), and key per-output state by name: state("wallpaper_" .. output, ...). Returning nil leaves that output’s instance empty. A window, popup or output = "active" panel has no output name and refuses a function child. Example: per-output wallpaper.

Reset on close

Named state keeps its value while a surface is hidden, so a reopened menu shows what it showed last. List the state a panel, window or popup owns in reset_on_close to start it fresh instead: when the surface stops being shown, each state goes back to its declared initial and each scroll to the top.

local open = state("picker_open", true)
local query = state("picker_query", "")
local list_scroll = scroll("picker_list")

return panel {
  id = "picker",
  layer = "overlay",
  visible = open,
  reset_on_close = { query, list_scroll },
  child = textfield { width = 300, height = 32, on_change = function(text) query:set(text) end },
}

A textfield’s draft is the engine’s and is not state; it follows its own lifetime.

Input region

A surface takes pointer input only where its content is solid; everywhere else clicks, hover and focus-follows-mouse pass through to what is below. The engine rebuilds this region on every pass.

A claiming box that clips its children ends the walk there; one that does not also claims the descendants sticking out of it, each cut to any clipping ancestor. visible = false subtrees claim nothing. To make an empty area catch clicks, put a rect { width = "fill", height = "fill", on_click = ... } there (click outside to close).

How do I…

Gotchas

See also: nodes, paint, input, signals, runtime, CLI.

Source: surface parsing, accepted properties, fingerprints, instances, function child and root size, input region, reload and hotplug.

panel

A layer-shell surface (zwlr_layer_surface_v1) pinned to screen edges: bars, docks, wallpapers, OSDs, launcher overlays, notification stacks. Rules every role shares are in surfaces.

A 32 px bar across the top of every output, reserving its height so windows start below it:

local function now(format)
    return mantle.clock:map(function(clock) return os.date(format, clock.time) end, "")
end

local function workspace(active)
    return rect { width = active and 20 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", align_v = "center" }
end

local bar = panel {
    id = "bar",
    layer = "top",
    anchor = { top = true, left = true, right = true },
    height = 32,
    exclusive_zone = true,
    child = row {
        width = "fill",
        height = "fill",
        padding = { left = 14, right = 14 },
        background = "#1e1e2e",
        children = {
            row { spacing = 6, align_v = "center", children = { workspace(false), workspace(true), workspace(false), workspace(false) } },
            rect { width = "fill" },
            row {
                spacing = 8,
                align_v = "center",
                children = {
                    text { content = now("%H:%M"), font_weight = 700, foreground = "#cdd6f4" },
                    text { content = now("%a %d %b"), foreground = "#a6adc8" },
                },
            },
            rect { width = "fill" },
            row {
                spacing = 12,
                align_v = "center",
                children = {
                    status("network-wireless-symbolic"),
                    status("bluetooth-active-symbolic"),
                    status("audio-volume-high-symbolic"),
                    text { content = "82%", foreground = "#a6e3a1", align_v = "center" },
                },
            },
        },
    },
}

return { bar }

Both horizontal edges are anchored, so the omitted width fills the root (size), and the two "fill" spacers centre the clock. The background sits on the row, not the panel, so the whole bar takes clicks (input region).

Properties

Beyond the shared properties. Structural fields, the types without Bound, refuse a signal and rebuild the surface when edited; live ones take a signal and update it in place (reload).

output

Connector names come from mantle.screens or niri msg outputs / hyprctl monitors.

Size

The table sizes the Wayland surface. On a spanned axis, omitted size also fills its root node. On an unspanned axis, omission measures the content. To keep a narrower box inside a spanned surface, put its size and background on a child. max_width/max_height cap the root.

Measured content is capped at the output minus the margins on the anchored edges, and by the root’s max_width/max_height. Other clients’ exclusive zones are not subtracted, so content wider than the space they leave is clipped by the compositor.

Exclusive zones

An integer zone counts from the output edge, so it must include the panel’s margin on that edge; true reserves the size alone.

Keyboard focus

Hiding a panel destroys its layer surface and showing creates a fresh one, so a constant keyboard_interactivity applies at every show. Bind it to a signal only to change the mode while the panel stays shown. This launcher opens on mantle toggle launcher_open from a compositor keybind, on the output the compositor picks, and closes on Escape:

local open = state("launcher_open", false)
local APPS = {
    { icon = "web-browser", name = "Web Browser" },
    { icon = "folder", name = "Files" },
    { icon = "utilities-terminal", name = "Terminal" },
}

local function result(index, app)
    return row {
        width = "fill",
        padding = 8,
        spacing = 12,
        radius = 8,
        background = index == 1 and "#89b4fa26" or "#00000000",
        children = {
            icon { name = app.icon, size = 24, align_v = "center" },
            text { content = app.name, foreground = "#cdd6f4", align_v = "center" },
        },
    }
end

local results = {}
for index, app in ipairs(APPS) do
    results[index] = result(index, app)
end

local launcher = panel {
    id = "launcher",
    layer = "overlay",
    output = "active",
    anchor = { top = true, bottom = true, left = true, right = true },
    width = "fill",
    height = "fill",
    visible = open,
    keyboard_interactivity = "exclusive",
    background = "#11111b99",
    child = column {
        width = 420, align_h = "center", align_v = "center",
        padding = 12, spacing = 8, radius = 14, background = "#1e1e2e",
        children = {
            rect {
                width = "fill",
                height = 36,
                padding = { left = 12, right = 12 },
                radius = 8,
                background = "#313244",
                children = {
                    textfield {
                        width = "fill",
                        height = "fill",
                        placeholder = "Search apps",
                        autofocus = true,
                        on_change = function(query) end,
                        on_cancel = function() open:set(false) end,
                    },
                },
            },
            column { width = "fill", spacing = 2, children = results },
        },
    },
}

return { launcher }

See named state and text fields.

Per-output content

local wallpaper = panel {
    id = "wallpaper",
    layer = "background",
    anchor = { top = true, bottom = true, left = true, right = true },
    exclusive_zone = "ignore",
    width = "fill",
    height = "fill",
    child = function(output)
        return image {
            source = state("wallpaper_" .. output, "/usr/share/backgrounds/default.jpg"),
            width = "fill",
            height = "fill",
        }
    end,
}

return { wallpaper }

mantle set wallpaper_DP-1 /path/to/picture.jpg changes one output’s picture (CLI, image). On the "background" layer only a node with a pointer handler takes input (input region), so the desktop stays click-through.

OSD

A card bottom-centre on the output the compositor picks, shown for 1.5 s after the level changes. No left/right anchor, so the width is measured and the protocol centres it:

local level = state("osd_level", 0.5)
local percent = level:map(function(value) return string.format("%d%%", math.floor(value * 100)) end)

local osd = panel {
    id = "osd",
    layer = "overlay",
    output = "active",
    anchor = { bottom = true },
    margin = { bottom = 96 },
    visible = pulse(level, 1500),
    background = "#1e1e2ee6", radius = 14, padding = 14,
    child = row {
        spacing = 12,
        children = {
            icon { name = "audio-volume-high-symbolic", size = 20, foreground = "#89b4fa", align_v = "center" },
            rect {
                width = 200, height = 8, align_v = "center", radius = 4, background = "#45475a",
                children = { rect { width = percent, height = "fill", radius = 4, background = "#89b4fa" } },
            },
            text { content = percent, width = 36, foreground = "#cdd6f4", align_v = "center" },
        },
    },
}

return { osd }

mantle set osd_level 0.7 shows it. Drive it from a capability by mapping, for example, mantle.audio to the level; see pulse. For a slide-in, animate the root’s translate, not the surface (animation).

How do I…

Dock on one output

Floating 8 px above the bottom edge. The zone is the dock’s 54 px plus its 8 px margin; exclusive_zone = true would reserve only the 54 px (exclusive zones):

local function app(name, running)
    return column {
        spacing = 2,
        children = {
            icon { name = name, size = 32 },
            rect { width = 4, height = 4, radius = 2, align_h = "center", background = running and "#89b4fa" or "#00000000" },
        },
    }
end

local dock = panel {
    id = "dock",
    layer = "bottom",
    output = "DP-1",
    anchor = { bottom = true },
    margin = { bottom = 8 },
    exclusive_zone = 62,
    background = "#1e1e2e", radius = 14, padding = 8,
    border_width = 1, border_color = "#ffffff14",
    child = row { spacing = 12, children = {
        app("web-browser", true),
        app("folder", false),
        app("utilities-terminal", false),
    } },
}

return { dock }

Close an overlay on an outside click

A full-screen panel with a transparent rect as its first child catches clicks everywhere; the card, declared after it, is on top and takes its own clicks:

local open = state("overlay_open", false)

local overlay = panel {
    id = "overlay",
    layer = "top",
    anchor = { top = true, bottom = true, left = true, right = true },
    width = "fill",
    height = "fill",
    visible = open,
    keyboard_interactivity = "on_demand",
    child = rect {
        width = "fill",
        height = "fill",
        children = {
            rect { width = "fill", height = "fill", on_click = function() open:set(false) end },
            column {
                width = 320, padding = 16, radius = 12, background = "#1e1e2e",
                margin = { top = 40, left = 40 },
                children = { text { content = "Quick settings", foreground = "#cdd6f4" } },
            },
        },
    },
}

return { overlay }

A rect stacks its children, so the card lies over the catcher. A click on the card lands on the card’s own buttons or on nothing; it never reaches the catcher.

Corner stack

Anchored to two edges, so both axes are measured and the panel grows with its cards:

local items = state("toasts", {
    { icon = "dialog-information-symbolic", color = "#89b4fa", title = "Build finished", body = "mantle built in 42 s" },
    { icon = "battery-caution-symbolic", color = "#fab387", title = "Battery at 20%", body = "About 1 h left" },
})

local stack = panel {
    id = "toasts",
    layer = "overlay",
    anchor = { top = true, right = true },
    margin = { top = 8, right = 8 },
    child = list {
        items = items,
        spacing = 8,
        each = function(toast)
            return row {
                width = 320, padding = 12, spacing = 12, radius = 12, background = "#1e1e2e",
                children = {
                    icon { name = toast.icon, size = 20, foreground = toast.color, align_v = "center" },
                    column {
                        spacing = 2,
                        children = {
                            text { content = toast.title, font_weight = 700, foreground = "#cdd6f4" },
                            text { content = toast.body, font_size = 12, foreground = "#a6adc8" },
                        },
                    },
                },
            }
        end,
    },
}

return { stack }

An empty list still maps a 1×1 px surface; bind visible to whether the list has items.

Gotchas

See also: surfaces, popup, input, signals, paint.

Source: panel spec, instances, layer shell, input region.

window

An xdg_toplevel: an application window the compositor places, tiles, decorates and closes. Use it for a settings window or a dialog; use a panel for anything pinned to the desktop. Rules every role shares are in surfaces.

local open = state("settings_open", false)
local page = state("settings_page", "General")
local TABS = {
    { name = "General", icon = "dialog-information-symbolic" },
    { name = "Display", icon = "display-brightness-symbolic" },
    { name = "Sound", icon = "audio-volume-high-symbolic" },
    { name = "Power", icon = "system-shutdown-symbolic" },
}

local function tab(entry)
    local selected = page:map(function(current) return current == entry.name end)
    return row {
        width = "fill",
        padding = { left = 10, right = 12, top = 8, bottom = 8 },
        spacing = 10,
        radius = 8,
        background = selected:map(function(on) return on and "#89b4fa26" or "#00000000" end),
        on_click = function() page:set(entry.name) end,
        children = {
            icon { name = entry.icon, size = 16, align_v = "center",
                   foreground = selected:map(function(on) return on and "#89b4fa" or "#a6adc8" end) },
            text { content = entry.name, foreground = "#cdd6f4", align_v = "center" },
        },
    }
end

local function switch(label, detail, on)
    return row {
        width = "fill",
        padding = 12,
        spacing = 12,
        children = {
            column { width = "fill", spacing = 2, align_v = "center", children = {
                text { content = label, foreground = "#cdd6f4" },
                text { content = detail, font_size = 12, foreground = "#a6adc8" },
            } },
            rect {
                width = 36, height = 20, radius = 10, align_v = "center",
                background = on and "#89b4fa" or "#45475a",
                children = { rect { width = 14, height = 14, radius = 7, margin = { left = 3, right = 3 },
                    align_h = on and "end" or "start", align_v = "center", background = on and "#ffffff" or "#bac2de" } },
            },
        },
    }
end

local function group(title, rows)
    local divided = {}
    for index, item in ipairs(rows) do
        if index > 1 then divided[#divided + 1] = rect { width = "fill", height = 1, margin = { left = 12, right = 12 }, background = "#313244" } end
        divided[#divided + 1] = item
    end
    return column { width = "fill", spacing = 10, children = {
        text { content = title, font_size = 12, font_weight = 700, foreground = "#89b4fa", margin = { left = 4 } },
        column { width = "fill", radius = 10, background = "#181825", children = divided },
    } }
end

local tabs = { text { content = "Settings", font_size = 15, font_weight = 700, foreground = "#cdd6f4", margin = { left = 10, top = 6, bottom = 10 } } }
for _, entry in ipairs(TABS) do tabs[#tabs + 1] = tab(entry) end

local settings = window {
    id = "settings",
    title = page:map(function(name) return "Settings: " .. name end),
    app_id = "org.example.settings",
    min_size = { width = 480, height = 360 },
    visible = open,
    on_close_request = function() open:set(false) end,
    child = row {
        width = "fill",
        height = "fill",
        background = "#1e1e2e",
        children = {
            column { width = 180, height = "fill", padding = 10, spacing = 2, background = "#181825", children = tabs },
            column { width = "fill", padding = 24, spacing = 18, children = {
                text { content = page, font_size = 22, font_weight = 700, foreground = "#cdd6f4" },
                group("Appearance", {
                    switch("Dark style", "Use dark colours in every window", true),
                    switch("Animations", "Ease panels and popups in and out", true),
                }),
                group("Clock", {
                    switch("Seconds", "Show seconds in the bar clock", false),
                    switch("24-hour time", "Show 13:00 instead of 1:00 PM", true),
                }),
            } },
        },
    },
}

return { settings }

mantle toggle settings_open opens it; the compositor’s close button or keybind closes it through on_close_request. The title follows the selected tab.

Properties

Beyond the shared properties. Every field but id and on_close_request takes a signal and updates the open window in place; a change while it is closed applies when it next opens.

By default the engine requests server-side decorations and draws none itself. decorations = "client" asks for none, and a compositor without zxdg_decoration_manager_v1 (or one that insists on its choice) decides regardless: the mode it chose is toplevel(id):state().decoration. Changing the property on a reload asks again.

Size

The window’s size is the compositor’s configure. The window node fills it on each axis where it has no width/height of its own; a set one sizes the node inside the window. Its child sizes to its content unless it sets "fill". A geometry_inset grows the surface past that size on each side (client-side decoration).

To set a floating window’s size or position, use compositor rules on app_id, or min_size for the opening size.

How do I…

Custom title bar

An app that draws its own frame asks the compositor to run the pointer: toplevel(id) takes a window’s id and has three pointer methods, called from an on_press (or an on_drag "start"), three state methods, and :state() (window state).

Compositors honour the pointer methods only for the serial of the press that started them, so a call from on_click, a timer or any other callback, on a hidden window, or on a press that landed on a different surface logs a warning and sends nothing. After a request the compositor owns the pointer and may send no release: the engine drops the drag and the armed click, so on_drag gets no "end" and on_click does not fire.

The state methods need no press and work from any callback. A request for a window that is not mapped yet is dropped; do not pair one with move() in the same press, as the move grab starts first.

local frame = toplevel("main")
local GRIP = 6

local function grip(edge, props)
    props.on_press = function(_, button)
        if button == "left" then frame:resize(edge) end
    end
    return rect(props)
end

return {
    window {
        id = "main",
        title = "Notes",
        child = column {
            width = "fill", height = "fill", background = "#1e1e2e",
            children = {
                grip("top", { width = "fill", height = GRIP, cursor = "n-resize" }),
                row {
                    width = "fill", height = 32, padding = { left = 12, right = 12 }, background = "#181825",
                    on_press = function(_, button)
                        if button == "left" then frame:move() else frame:show_menu() end
                    end,
                    children = { text { content = "Notes", foreground = "#cdd6f4", align_v = "center" } },
                },
                grip("bottom_right", { width = GRIP, height = GRIP, align_h = "end", cursor = "se-resize" }),
            },
        },
    },
}

Window state

toplevel(id):state() is a read-only signal of what the compositor last configured the window to be, so the app’s own frame can follow it. It is rewritten only when a configure changes a value. Before the first configure and after the window closes it holds the default: every flag false, no bounds, every capability true, decoration = "client". Reading it never requests a change; :set_maximized, :set_minimized and :set_fullscreen do.

local focused = toplevel("main"):state():map(function(s) return s.activated end)

return {
    window {
        id = "main",
        title = "Notes",
        decorations = "client",
        child = rect {
            width = "fill", height = "fill",
            background = focused:map(function(on) return on and "#1e1e2e" or "#313244" end),
        },
    },
}

Client-side decoration

A window that draws its own frame can also draw its shadow and rounded corners outside it. geometry_inset adds a band around the window’s frame: the buffer is the frame plus the band, the window node fills the whole buffer, and the compositor sizes, tiles and snaps by the frame alone (xdg_surface.set_window_geometry). Configure sizes, min_size and max_size are all the frame’s. The child fills the buffer too if it says "fill"; give the frame a margin of the band, and its shadows and radius draw into the band.

Compositors expect no shadow on a maximized, fullscreen or tiled edge. The engine does not guess: bind geometry_inset to the window state and zero those edges.

local frame = toplevel("main")
local SHADOW = 24

local function band(s)
    if s.maximized or s.fullscreen then return 0 end
    return {
        left = s.tiled.left and 0 or SHADOW, right = s.tiled.right and 0 or SHADOW,
        top = s.tiled.top and 0 or SHADOW, bottom = s.tiled.bottom and 0 or SHADOW,
    }
end
local inset = frame:state():map(band)
local floating = frame:state():map(function(s)
    local t = s.tiled
    return not (s.maximized or s.fullscreen or t.left or t.right or t.top or t.bottom)
end)

local GRIP = 8
local function grip(edge, cursor, props)
    props.background = "#00000000"
    props.cursor = cursor
    props.visible = floating
    props.on_press = function(_, button)
        if button == "left" then frame:resize(edge) end
    end
    return rect(props)
end

return {
    window {
        id = "main",
        title = "Notes",
        decorations = "client",
        geometry_inset = inset,
        child = rect {
            width = "fill", height = "fill",
            children = {
                column {
                    width = "fill", height = "fill", margin = inset, background = "#1e1e2e",
                    radius = floating:map(function(on) return on and 10 or 0 end),
                    shadows = { { color = "#00000080", blur = 18, offset = { x = 0, y = 4 } } },
                    children = {
                        row {
                            width = "fill", height = 32, padding = { left = 12 }, background = "#181825",
                            on_press = function(_, button)
                                if button == "left" then frame:move() else frame:show_menu() end
                            end,
                            children = { text { content = "Notes", foreground = "#cdd6f4", align_v = "center" } },
                        },
                    },
                },
                grip("top", "n-resize", { width = "fill", height = GRIP }),
                grip("bottom", "s-resize", { width = "fill", height = GRIP, align_v = "end" }),
                grip("left", "w-resize", { width = GRIP, height = "fill" }),
                grip("right", "e-resize", { width = GRIP, height = "fill", align_h = "end" }),
            },
        },
    },
}

The rect root stacks its children, so the grips lie over the band’s edges: a transparent background makes each one claim input (input region), and visible = floating removes them when the window is maximized, fullscreen or tiled. The shadow itself is not content and takes no pointer input. Corner grips are more of the same, sized GRIP * 2 and listed after the edges.

Confirm before closing

on_close_request is a request, so it can open a question instead of closing:

local open = state("editor_open", true)
local confirming = state("editor_confirm", false)

local editor = window {
    id = "editor",
    title = "Editor",
    visible = open,
    on_close_request = function() confirming:set(true) end,
    child = column {
        width = "fill", height = "fill", padding = 16, spacing = 8, background = "#1e1e2e",
        children = {
            text { content = "Unsaved changes", foreground = "#cdd6f4" },
            row {
                spacing = 8,
                visible = confirming,
                children = {
                    rect { padding = 8, background = "#f38ba8",
                        on_click = function() confirming:set(false); open:set(false) end,
                        children = { text { content = "Discard" } } },
                    rect { padding = 8, background = "#313244",
                        on_click = function() confirming:set(false) end,
                        children = { text { content = "Cancel", foreground = "#cdd6f4" } } },
                },
            },
        },
    },
}

return { editor }

Gotchas

See also: surfaces, popup, nodes, signals.

Source: window spec, window, root size.

popup

An xdg_popup on a shown panel, window or popup: a dropdown, context menu or tooltip. The compositor places it against a rectangle in the parent, keeps it on screen and, with a grab, dismisses it on an outside click, which a second panel cannot do. A hidden popup has no Wayland object. Rules every role shares are in surfaces.

local menu_open = state("menu_open", false)
local menu_anchor = state("menu_anchor", { x = 0, y = 0, width = 1, height = 1 })

local function item(icon_name, label, color)
    return row {
        width = "fill",
        padding = 8,
        spacing = 10,
        radius = 6,
        children = {
            icon { name = icon_name, size = 16, foreground = color, align_v = "center" },
            text { content = label, foreground = color, align_v = "center" },
        },
    }
end

local bar = panel {
    id = "bar",
    layer = "top",
    anchor = { top = true, left = true, right = true },
    width = "fill",
    height = 32,
    exclusive_zone = true,
    child = row {
        width = "fill", height = "fill", background = "#1e1e2e",
        children = {
            rect {
                padding = 8,
                on_click = function(rect)
                    menu_anchor:set(rect)
                    menu_open:set(not menu_open:get())
                end,
                children = { icon { name = "system-shutdown-symbolic", size = 16, foreground = "#f38ba8" } },
            },
        },
    },
}

local menu = popup {
    id = "menu",
    parent = "bar",
    anchor_rect = menu_anchor,
    anchor = "bottom",
    gravity = "bottom_right",
    offset = { x = 4, y = 4 },
    visible = menu_open,
    on_dismiss = function() menu_open:set(false) end,
    child = column {
        width = 170, padding = 4, radius = 10, background = "#1e1e2e",
        border_width = 1, border_color = "#45475a",
        children = {
            item("system-lock-screen-symbolic", "Lock", "#cdd6f4"),
            item("system-log-out-symbolic", "Log out", "#cdd6f4"),
            item("system-reboot-symbolic", "Restart", "#cdd6f4"),
            item("system-shutdown-symbolic", "Power off", "#f38ba8"),
        },
    },
}

return { bar, menu }

A dropdown under a bar button. on_click’s rect is the button in its surface’s coordinates, which is what anchor_rect takes (pointer input). An outside click dismisses it and on_dismiss clears the state.

Properties

Beyond the shared properties. Every field but id, parent, on_dismiss, on_escape and reset_on_close takes a signal.

Placement

While a popup is open, a change to its measured size or to any positioner field moves it through xdg_popup.reposition. Below xdg_popup version 3 it keeps the size and place it opened at until it closes, and logs a warning.

Grab

A grab needs a mouse button press or release on one of the shell’s surfaces in the same turn, so open a grabbing popup from on_click. Without one the popup stays closed and a warning is logged. A compositor that denies the grab dismisses the popup, and on_dismiss runs.

Dismissal

A compositor dismissal destroys the popup but leaves your visible signal true. The engine latches it shut until the next pointer press or release on the shell, then opens it again. Clear your state in on_dismiss, as the example at the top does.

Hiding or dismissing a popup also closes the popups open under it and latches them the same way, so each one whose visible stays true reopens on the next press.

How do I…

Nested menus

A popup can parent another popup. The submenu hangs off the right edge of the clicked row and flips left near the screen edge:

local sub_open = state("sub_open", false)
local sub_anchor = state("sub_anchor", { x = 0, y = 0, width = 1, height = 1 })

local power_row = rect {
    padding = 4,
    on_click = function(rect)
        sub_anchor:set(rect)
        sub_open:set(true)
    end,
    children = { text { content = "Power ›" } },
}

local submenu = popup {
    id = "power_menu",
    parent = "menu",
    anchor_rect = sub_anchor,
    anchor = "top_right",
    gravity = "bottom_right",
    constraint_adjustment = { "flip_x", "slide_y" },
    visible = sub_open,
    on_dismiss = function() sub_open:set(false) end,
    background = "#1e1e2e", padding = 8,
    child = column { spacing = 4, children = { text { content = "Suspend" }, text { content = "Reboot" } } },
}

power_row goes inside the menu popup. on_click’s rect is in the menu’s own coordinates, which is what a child popup’s anchor_rect expects. Set sub_open to false wherever the menu closes (its on_dismiss included), or the submenu reopens on the next click.

Tooltip

A hover opens no grab, so grab = false. hover_rect tracks the hovered node and is 1×1 before the first hover, which keeps anchor_rect valid:

local clock = text { content = "12:30", padding = 8, hover = hover("clock") }

local tooltip = popup {
    id = "clock_tooltip",
    parent = "bar",
    anchor_rect = hover_rect("clock"),
    anchor = "bottom",
    gravity = "bottom",
    offset = { y = 4 },
    grab = false,
    visible = hover("clock"),
    background = "#1e1e2e", radius = 6, padding = 6,
    child = text { content = "Thursday, 24 September" },
}

clock goes inside the bar panel.

Anchor to a node’s geometry

Bind geometry. It reads zero before the first layout, so map it to a 1×1 fallback. With no click to open it, it needs grab = false:

local battery = text { content = "87%", padding = 8, geometry = geometry("battery") }

local details = popup {
    id = "battery_details",
    parent = "bar",
    anchor_rect = geometry("battery"):map(function(rect)
        return rect.width > 0 and rect or { x = 0, y = 0, width = 1, height = 1 }
    end),
    anchor = "bottom",
    gravity = "bottom",
    grab = false,
    visible = state("battery_open", false),
    child = text { content = "2 h 10 min left" },
}

Gotchas

See also: surfaces, panel, input, signals.

Source: popup spec, popup, instances.

lock

The session lock screen: one ext_session_lock_surface_v1 per connected output, covering it for as long as the compositor holds the session locked. Declaring a lock does not lock; mantle.lock:lock() does, and only a correct password typed into its secure field unlocks. The lock’s state (active, prompt, messages, authenticating, attempts, error, unlocking) and actions are on the lock capability. Rules every role shares are in surfaces.

mantle.lock:set_unlock_animation(250)

local up = mantle.lock:map(function(lock) return lock.active and not lock.unlocking end, false)

local function now(format)
    return mantle.clock:map(function(clock) return os.date(format, clock.time) end, "")
end

local hint = mantle.lock:map(function(lock)
    if lock.error ~= "" then return string.format("%s (%d)", lock.error, lock.attempts) end
    if lock.authenticating then return "Checking…" end
    if lock.prompt then return lock.prompt.text end
    return lock.active and "Enter your password" or "Locking…"
end, "")

local lock_screen = lock {
    id = "lock",
    background = "#11111b",
    child = function(output)
        return column {
            width = "fill", height = "fill", align_v = "center", spacing = 12,
            opacity = up:map(function(on) return on and 1 or 0 end),
            animate = { opacity = { duration = 200, from = 0 } },
            children = {
                text { content = now("%H:%M"), font_size = 72, font_weight = 700, foreground = "#cdd6f4", align_h = "center" },
                text { content = now("%A, %d %B"), font_size = 16, foreground = "#a6adc8", align_h = "center" },
                text { content = output, font_size = 12, foreground = "#6c7086", align_h = "center", margin = { top = 24 } },
                rect {
                    width = 300, align_h = "center", padding = { left = 16, right = 16, top = 10, bottom = 10 },
                    radius = 999, background = "#1e1e2e", border_width = 1, border_color = "#45475a",
                    children = {
                        textfield {
                            width = "fill",
                            height = 20,
                            placeholder = "Password",
                            mask_character = "•",
                            masked = mantle.lock:map(function(lock) return not (lock.prompt and lock.prompt.echo) end, true),
                            secure_submit = { capability = "lock", action = "authenticate" },
                        },
                    },
                },
                text {
                    content = hint,
                    foreground = mantle.lock:map(function(lock) return lock.error ~= "" and "#f38ba8" or "#a6adc8" end, "#a6adc8"),
                    align_h = "center",
                },
            },
        }
    end,
}

action("lock", function() mantle.lock:lock() end)

return { lock_screen }

mantle call lock from a keybind (action) locks the session. Each output gets its own card; the field is typable as soon as the compositor gives the lock the keyboard, with no click. After a correct password the lock stays up 250 ms while the card fades out, then the session unlocks.

Properties

A lock takes id, child and the common and box node properties, minus the ones the protocol owns.

output and anchor are refused too: the protocol owns coverage and lifetime. The root is the output’s size; give children "fill" to cover it. A reload that renames id while the session is locked is refused with a warning in mantle log. A config declares at most one lock; a second is refused at evaluation.

When a lock is refused

The compositor keeps the session locked if the shell dies, so a lock screen with no way to type a password leaves only a VT switch. mantle.lock:lock() checks the lock screen before it asks the compositor. A refusal leaves the session unlocked and puts the reason in mantle.lock’s error and in mantle.rescue.

The field’s keystrokes go to PAM and never reach Lua.

How do I…

Gotchas

See also: lock capability, secure fields, surfaces, animation.

Source: lock spec, at most one lock, session lock, authenticate check, rename while locked.

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.

rect

A plain box that stacks its children: each one gets the whole content box and places itself with align_h/align_v. Use it for a filled shape, a background behind something, or layering one node over another. Side by side needs a row or column instead.

A bell icon with an unread badge in its top-right corner:

local unread = state("unread", 3)

local bell = rect {
    width = 40,
    height = 40,
    radius = 12,
    background = "#313244",
    children = {
        icon { name = "notification-symbolic", size = 22, foreground = "#CDD6F4",
               align_h = "center", align_v = "center" },
        rect {
            visible = unread:map(function(n) return (n or 0) > 0 end),
            align_h = "end",
            align_v = "start",
            margin = { top = 4, right = 4 },
            padding = { left = 5, right = 5 },
            radius = 8,
            background = "#F38BA8",
            children = { text { content = unread:map(tostring), font_size = 11, font_weight = 700, foreground = "#11111B" } },
        },
    },
}

return bell

The badge comes second, so it paints over the icon.

Properties

rect takes the common and box properties, plus:

Without width and height, a rect is the union of its children, and 0 × 0 with none.

How do I…

Centre something

A stacking parent places each child on its own, so align_h and align_v of "center" centre it. Here a card sits in the middle of a full-screen dimmed layer.

local dialog = rect {
    width = "fill",
    height = "fill",
    background = "#00000080",
    children = {
        column {
            align_h = "center",
            align_v = "center",
            padding = 24,
            radius = 12,
            background = "#1E1E2E",
            children = { text { content = "Centred", font_size = 16 } },
        },
    },
}

Inside a row, set align_h = "center" on the row instead: it packs its children, and they ignore their own align_h.

Gotchas

See also: row and column, paint.

Source: vocabulary, children, box paint.

row and column

Boxes that flow their children along one axis: a row left to right, a column top to bottom. They are the main layout tools; everything else is placed inside one. The two accept the same properties and differ only in their main axis. For children built from data, use a list.

A meter: a "fill"-wide track with a percentage-wide fill that follows a signal.

local volume = state("volume", 0.45)
local percent = volume:map(function(v) return string.format("%d%%", math.floor((v or 0) * 100 + 0.5)) end)

local meter = row {
    width = "fill",
    height = 6,
    radius = 3,
    align_v = "center",
    background = "#313244",
    children = { rect { width = percent, height = "fill", radius = 3, background = "#89B4FA", animate = { width = 150 } } },
}

return row {
    width = 280,
    padding = 14,
    spacing = 12,
    radius = 12,
    background = "#1E1E2E",
    children = {
        icon { name = "audio-volume-medium-symbolic", size = 18, foreground = "#89B4FA", align_v = "center" },
        meter,
        text { content = percent, foreground = "#CDD6F4", align_v = "center" },
    },
}

Properties

row and column take the common and box properties, plus:

How the container packs its children:

"fill" children along the main axis share what the others leave, and no child shrinks; see sizes.

How do I…