antle

Introduction

Mantle runs a desktop shell written in Lua on Wayland. The engine evaluates your shell.lua, which returns the surfaces to show (bars, windows, popups, a lock screen). Each surface holds a tree of nodes, and any node property can be a live signal that updates itself when a capability (audio, workspaces, the clock) pushes new state.

Build the first shell below, then find the rest by topic or by task. The glossary defines every term.

Your first shell

1. Create the config

mantle init -c ~/.config/mantle

It writes a starter shell.lua and a .luarc.json that points lua-language-server at the API stubs, so your editor completes and type-checks. The config is a directory, not a file (init).

2. A first bar

shell.lua runs top to bottom and returns one surface or an array of them. This bar shows a launcher button, the workspaces of the first output and a clock. The button and a keybind share one piece of named state, launcher_open, which shows a second panel.

local launcher_open = state("launcher_open", false)

local clock = text {
    content = mantle.system:map(function(system)
        return os.date("%H:%M", system and system.time)
    end),
    foreground = "#cdd6f4",
}

local workspaces = list {
    direction = "Horizontal",
    spacing = 4,
    source = mantle.workspaces:map(function(ws)
        return ws and ws.outputs[1] and ws.outputs[1].workspaces or {}
    end),
    key = function(workspace) return tostring(workspace.id) end,
    itemfn = function(workspace)
        return button {
            padding = { left = 6, right = 6 },
            radius = 4,
            background = workspace.populated and "#45475a" or "#00000000",
            on_click = function()
                mantle.workspaces:focus(workspace.id)
            end,
            children = { text { content = tostring(workspace.idx), foreground = "#cdd6f4" } },
        }
    end,
}

local launcher_button = button {
    padding = { left = 8, right = 8 },
    background = launcher_open:map(function(open) return open and "#89b4fa" or "#313244" end),
    on_click = function() launcher_open:set(not launcher_open:get()) end,
    children = { text { content = "Apps", foreground = "#cdd6f4" } },
}

return {
    panel {
        id = "bar",
        layer = "Top",
        anchor = { top = true, left = true, right = true },
        exclusive = true,
        width = "Fill",
        height = 32,
        background = "#1e1e2ee6",
        child = row {
            width = "Fill",
            align_v = "Center",
            spacing = 8,
            padding = { left = 8, right = 8 },
            children = { launcher_button, workspaces, rect { width = "Fill" }, clock },
        },
    },
    panel {
        id = "launcher",
        layer = "Overlay",
        visible = launcher_open,
        keyboard_interactivity = "OnDemand",
        width = 400,
        height = 300,
        background = "#1e1e2e",
        radius = 12,
        child = text { content = "Launcher", foreground = "#cdd6f4" },
    },
}

3. Run it

4. Edit it live

Saving any .lua or .frag file under the config directory re-evaluates shell.lua in the same process, and named state keeps its value. A reload whose evaluation raises keeps the previous scene on screen, logs the error and sets mantle.rescue, which a config can draw as an error banner. The next successful reload clears it. What a reload keeps: what survives it.

5. Split into modules

require("widgets.clock") loads widgets/clock.lua from the config directory, and nothing outside it. Bind every require to a local before listing it in a table: it returns the module and its file path. Example and rules: modules.

6. Bind a key

mantle toggle <name> flips a declared boolean state in the running shell, so the launcher above opens from the compositor:

# Hyprland (hyprland.conf)
bind = SUPER, A, exec, mantle toggle launcher_open
# Hyprland (Lua config)
hl.bind("SUPER + A", hl.dsp.exec_cmd("mantle toggle launcher_open"))
# niri (config.kdl, inside binds {})
Mod+A { spawn "mantle" "toggle" "launcher_open"; }

mantle set writes any value, and mantle call runs an action (commands).

Topic index

The sidebar’s order. Every guide, surface and node page ends with How do I… and Gotchas tables.

Editor completion comes from the lua-meta/ stubs that mantle init wires up; mantle.lua is generated from the Rust capability types. DECISIONS.md records why each contract is what it is, cited as ADR-NNNN.

How do I…

Source: init, starter, CLI, watcher, reload and rescue, require path.

Installation

What Mantle needs, how to install it, and how to start it with the session. The introduction walks through a first config.

mantle init           # ~/.config/mantle/shell.lua and a .luarc.json for lua-language-server
mantle check          # evaluate it with no Wayland; exits 1 on an error
mantle -d             # run the shell detached
mantle log -f         # follow its output

Requirements

A capability starts on the config’s first mantle.<name> read and needs its backend only from then. What each one does without it is in its page’s Backend section.

system, files, storage and processes need nothing beyond the paths and programs the config names.

Install

mantle starts mantle-renderer from its own directory, so both must come from one build (binaries).

A source build needs a C compiler and pkg-config for the vendored Lua, clang for PipeWire’s bindings, and the development files of what the binaries link:

Rust 1.89 or later comes from rustup where the distro’s cargo is older. Mantle is developed and run on Arch. The Fedora and Debian 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 for now.

Two optional system files ship in packaging/:

Set up a config

mantle init writes a starter shell.lua (a one-clock bar) and a .luarc.json into the config directory, ~/.config/mantle by default (which config). It keeps an existing file unless given --force.

The .luarc.json points lua-language-server at the lua-meta/ stubs, which give completion and type checks for every node, surface and capability. 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, rewriting any stub that differs, and mantle check says when they are out of date. The .luarc.json also raises LuaLS’s type-check, unbalanced, strict and global groups and unused-local to warnings in every file, so a wrong type or a dead require shows up.

Run the shell

Launch mantle from inside the compositor session: workspaces, windows and keyboard find niri or Hyprland through the environment the session sets. Every other command is on the CLI page.

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 0.1`.
action("volume.up", function(step)
    local audio = mantle.audio:get()
    if not audio or not audio.volume then
        error("no default output yet")
    end
    local volume = math.min(1.0, audio.volume + (step or 0.05))
    mantle.audio:set_volume(volume)
    return string.format("%d%%", math.floor(volume * 100 + 0.5))
end)

return panel {
    id = "launcher",
    layer = "Overlay",
    keyboard_interactivity = "OnDemand",
    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. 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 0.1 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. --detached is the flag -d passes to the copy it starts; typed by hand, it is ignored and the shell runs in the foreground.

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 an undeclared name, 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.

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 twice with the real layout code, on one 1920x1080 output plus one per monitor name a panel pins:

It prints <path>: ok, N surface(s) and one <role> <id> line per surface, preceded by anything the config printed. An error prints as <config dir>: <error> and exits 1; files in it are named relative to the config directory. A layout error names its pass, <config dir>: <pass>: layout: <error>, once per failing pass. 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 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:3: in main chunk
/home/me/.config/mantle: before capability data: layout: invalid value for `children`: on `bar@DP-1`: row[0] (shell.lua:7) > children[0]: shell.lua:2: `text` has no property `contnet`; did you mean `content`?
/home/me/.config/mantle: before capability data: layout: invalid value for `content`: on `bar@DP-1`: text[0] (shell.lua:9) > Signal getter on a `text` node failed: signal created at shell.lua:3: shell.lua:4: attempt to index a number value (local 'n')
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.

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

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 client, state writes, check, init, log, levels.

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.system:map(function(system)
        return system and os.date("%H:%M", system.time) or "" -- nil before the first push
    end),
    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. dofile and loadfile remain and read any path, but they are synchronous file I/O on the render thread. To read a file, use process.run or persistent_table. 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:

A failed reload keeps only the scene. The actions, timers, on_change handlers and idle thresholds of the evaluation that drew it are already cleared (what survives). A failed evaluation leaves none registered. A failed apply keeps the new evaluation’s actions, handlers and thresholds but no timers. 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 ~= nil and state.is_rescue end),
    background = "#f38ba8ff",
    padding = 8,
    child = text {
        content = rescue:map(function(state) return state and state.error_log or "" 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, 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, under 5 ms: one nil check, one index, one format.
local battery_label = mantle.battery:map(function(battery)
    if not battery or not battery.present then
        return "" -- nil until the first push; 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 clock = mantle.system:map(function(system)
  if not system then return "--:--" end -- nil until the first push
  return os.date("%H:%M", system.time)
end)

return panel {
  id = "bar", layer = "Top", anchor = { top = true, left = true, right = true }, height = 28,
  child = row { spacing = 12, children = {
    text { content = clock },       -- live: follows every push
    text { content = clock:get() }, -- snapshot: "--:--" until the next reload
  } },
}

A capability (mantle.<name>, see capabilities) is a signal too. It reads nil until its first snapshot arrives (hydration), and in mantle check’s first pass, before a sample push. Every function that reads a capability must handle nil. When a signal resolves to nil, its property counts as absent and takes the property’s default.

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 works 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

Derived signals

:map and computed run again once a signal they read is written, and their readers re-resolve only when the result changed (what a node reads again): a scalar or a plain-data table by value, anything holding a function, signal or metatable on every run. An HH:MM label or a { { text = hour, bold = true } } run list mapped from a per-second snapshot re-resolves once a minute. Within one pass, a derived signal read by several properties runs once. Keep their functions cheap and side-effect free: no :set, no process, no action. They run under the CPU budget and nesting limit described in runtime. Side effects belong in on_click, a capability’s on_change (capabilities) or a timer (scripting).

A derived colour:

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

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.system, show_seconds }, function(system, seconds)
  if not system then return "" end
  return os.date(seconds and "%H:%M:%S" or "%H:%M", system.time)
end)

button {
  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

button {
  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) },
} }

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.

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.

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.

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, itemfn, 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.

How do I…

Derive from two capabilities

List every source in computed. Each one reads nil until its first push.

local status = computed({ mantle.network, mantle.audio }, function(network, audio)
  if not network or not audio then return "..." end
  local net = network.connected and "online" or "offline"
  local sound = audio.muted and "muted" or string.format("%d%%", math.floor((audio.volume or 0) * 100))
  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 = true,
    width = "Fill",
    child = function(output)
        return row {
            width = "Fill",
            height = "Fill",
            padding = { left = 12, right = 12 },
            background = "#1e1e2e",
            children = { text { content = output, foreground = "#cdd6f4", align_v = "Center" } },
        }
    end,
}

return { bar }

Properties every role takes

Every surface takes id (required) and one child node. The root is itself a box node, so it also takes the common and box node properties: 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 monitor = "Active" panel has no output name and refuses a function child. Example: per-output wallpaper.

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; visible = false subtrees claim nothing. To make an empty area catch clicks, put a button { 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 clock = mantle.system:map(function(system)
    return system and os.date("%H:%M", system.time) or ""
end)

local bar = panel {
    id = "bar",
    layer = "Top",
    anchor = { top = true, left = true, right = true },
    width = "Fill",
    height = 32,
    exclusive = true,
    child = row {
        width = "Fill",
        height = "Fill",
        padding = { left = 12, right = 12 },
        background = "#1e1e2e",
        children = {
            text { content = "Workspaces", foreground = "#cdd6f4", align_v = "Center" },
            rect { width = "Fill" },
            text { content = clock, foreground = "#cdd6f4", align_v = "Center" },
            rect { width = "Fill" },
            text { content = "Tray", foreground = "#cdd6f4", align_v = "Center" },
        },
    },
}

return { bar }

The panel’s width = "Fill" makes the root node as wide as the surface (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).

monitor

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

Size

The table sizes the Wayland surface. The root node inside it is laid out like any node: omitted means content-sized even when the surface spans the output. On a spanned axis write "Fill" on the panel so the root, its background and its "Fill" children cover the surface.

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

The zone counts from the output edge, so it includes the panel’s margin on that edge.

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 launcher = panel {
    id = "launcher",
    layer = "Overlay",
    monitor = "Active",
    anchor = { top = true, bottom = true, left = true, right = true },
    width = "Fill",
    height = "Fill",
    visible = open,
    keyboard_interactivity = "Exclusive",
    background = "#11111b99",
    child = column {
        width = 480, align_h = "Center", align_v = "Center",
        padding = 16, radius = 12, background = "#1e1e2e",
        children = {
            textfield {
                width = "Fill",
                height = 32,
                placeholder = "Search",
                autofocus = true,
                on_change = function(query) end,
                on_cancel = function() open:set(false) end,
            },
        },
    },
}

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 = "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 button with a 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 osd = panel {
    id = "osd",
    layer = "Overlay",
    monitor = "Active",
    anchor = { bottom = true },
    margin = { bottom = 96 },
    visible = pulse(level, 1500),
    background = "#1e1e2ee6", radius = 12, padding = 12,
    child = row {
        spacing = 12,
        children = {
            text { content = "Volume" },
            rect {
                width = 200, height = 8, align_v = "Center", radius = 4, background = "#45475a",
                children = {
                    rect {
                        width = level:map(function(value) return string.format("%d%%", math.floor(value * 100)) end),
                        height = "Fill", radius = 4, background = "#89b4fa",
                    },
                },
            },
        },
    },
}

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 48 px plus its 8 px margin; exclusive = true would reserve only the 48 px (exclusive zones):

local dock = panel {
    id = "dock",
    layer = "Bottom",
    monitor = "DP-1",
    anchor = { bottom = true },
    margin = { bottom = 8 },
    exclusive = 56,
    background = "#1e1e2e", radius = 12, padding = 8,
    child = row { spacing = 8, children = {
        icon { name = "web-browser", size = 32 },
        icon { name = "folder", size = 32 },
        icon { name = "utilities-terminal", size = 32 },
    } },
}

return { dock }

Close an overlay on an outside click

A full-screen panel with a transparent button 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 = "OnDemand",
    child = rect {
        width = "Fill",
        height = "Fill",
        children = {
            button { 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", { "Build finished", "Battery at 20%" })

local stack = panel {
    id = "toasts",
    layer = "Overlay",
    anchor = { top = true, right = true },
    margin = { top = 8, right = 8 },
    child = list {
        source = items,
        spacing = 8,
        itemfn = function(message)
            return rect {
                width = 320, padding = 12, radius = 12, background = "#1e1e2e",
                children = { text { content = message, foreground = "#cdd6f4" } },
            }
        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 function tab(name)
    return button {
        width = "Fill",
        padding = { left = 12, right = 12, top = 8, bottom = 8 },
        radius = 8,
        background = page:map(function(current) return current == name and "#313244" or "#00000000" end),
        on_click = function() page:set(name) end,
        children = { text { content = name, foreground = "#cdd6f4" } },
    }
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 = function() open:set(false) end,
    child = row {
        width = "Fill",
        height = "Fill",
        background = "#1e1e2e",
        children = {
            column { width = 160, height = "Fill", padding = 8, spacing = 4, background = "#181825",
                children = { tab("General"), tab("Display"), tab("Sound"), tab("Power") } },
            column { width = "Fill", padding = 24,
                children = { text { content = page, font_size = 20, foreground = "#cdd6f4" } } },
        },
    },
}

return { settings }

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

Properties

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

The engine requests server-side decorations and draws none itself. A compositor that insists on client-side decorations gets an undecorated window, with a log line.

Size

The window’s size is the compositor’s configure. The root fills it on each axis where it has no width/height of its own; a set one sizes the root inside the window.

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…

Confirm before closing

on_close 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 = 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 = {
                    button { padding = 8, background = "#f38ba8",
                        on_click = function() confirming:set(false); open:set(false) end,
                        children = { text { content = "Discard" } } },
                    button { 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 bar = panel {
    id = "bar",
    layer = "Top",
    anchor = { top = true, left = true, right = true },
    width = "Fill",
    height = 32,
    exclusive = true,
    child = row {
        width = "Fill", height = "Fill", background = "#1e1e2e",
        children = {
            button {
                padding = 8,
                on_click = function(rect)
                    menu_anchor:set(rect)
                    menu_open:set(not menu_open:get())
                end,
                children = { text { content = "Menu", foreground = "#cdd6f4" } },
            },
        },
    },
}

local menu = popup {
    id = "menu",
    parent = "bar",
    anchor_rect = menu_anchor,
    anchor = "Bottom",
    gravity = "Bottom",
    offset = { y = 4 },
    visible = menu_open,
    on_dismiss = function() menu_open:set(false) end,
    child = column {
        width = 160, padding = 12, spacing = 10, radius = 10, background = "#1e1e2e",
        border_width = 1, border_color = "#45475a",
        children = {
            text { content = "Settings", foreground = "#cdd6f4" },
            text { content = "Log out", foreground = "#cdd6f4" },
        },
    },
}

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 and on_dismiss 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 left, right or middle 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 = button {
    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 = "TopRight",
    gravity = "BottomRight",
    constraint_adjustment = { "FlipX", "SlideY" },
    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, 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 ~= nil and lock.active and not lock.unlocking end)

local hint = mantle.lock:map(function(lock)
    if lock == nil then return "" end
    if lock.error ~= "" then return string.format("%s (%d)", lock.error, lock.attempts) end
    if lock.authenticating then return "Checking…" 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 = output, foreground = "#6c7086", align_h = "Center" },
                rect {
                    width = 320, align_h = "Center", padding = 8, radius = 18, background = "#1e1e2e",
                    children = {
                        textfield {
                            width = "Fill",
                            height = 20,
                            placeholder = "Password",
                            mask_character = "•",
                            secure_submit = { capability = "lock", action = "authenticate" },
                        },
                    },
                },
                text { content = hint, foreground = "#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.

monitor 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 bar = panel {
    id = "bar",
    layer = "Top",
    anchor = { top = true, left = true, right = true },
    exclusive = 32,
    width = "Fill",
    height = 32,
    child = row {
        width = "Fill",
        height = "Fill",
        padding = { left = 8, right = 8 },
        background = "#1E1E2ECC",
        children = {
            row { width = "Fill", align_v = "Center", spacing = 6, children = {
                text { content = "left", foreground = "#CDD6F4" },
            } },
            text { content = clock, align_v = "Center", foreground = "#CDD6F4" },
            row { width = "Fill", align_h = "End", align_v = "Center", spacing = 6, children = {
                text { content = "right", foreground = "#CDD6F4" },
            } },
        },
    },
}

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.

The four surface roles (panel, window, popup, lock) are node kinds too: they take the common and box properties 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.

Of the leaves, only text and icon measure themselves. image, capture, shader and textfield have no intrinsic size: without width and height they are 0 × 0 and draw nothing.

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 spill out, cut by the parent’s clip, 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. Neither is range-checked, so negatives are accepted. 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

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, button and the four surface roles also take background, radius, corner_shape, border_color, border_width, clip, mask, blur, backdrop_blur and shadow_mode. 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, label)
    return column {
        id = name, -- a new id per view: the old view leaves and fades instead of being reused
        padding = 12,
        opacity = 1, -- `from` needs the property set
        animate = { opacity = { duration = 150, from = 0 }, exit = { duration = 150, opacity = 0 } },
        children = { text { content = label } },
    }
end

local views = {
    wifi = function() return page("wifi", "Wi-Fi networks") end,
    bluetooth = function() return page("bluetooth", "Bluetooth devices") end,
}

local body = rect {
    width = 300,
    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 and 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. Reach for 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 = 28,
    height = 28,
    children = {
        icon { name = "notification-symbolic", size = 20, 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",
            padding = { left = 4, right = 4 },
            radius = 7,
            background = "#F38BA8",
            children = { text { content = unread:map(tostring), font_size = 10, 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, button, 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 meter = row {
    width = "Fill",
    height = 6,
    radius = 3,
    background = "#313244",
    children = { rect {
        width = volume:map(function(v) return string.format("%d%%", math.floor((v or 0) * 100 + 0.5)) end),
        height = "Fill",
        radius = 3,
        background = "#89B4FA",
        animate = { width = 150 },
    } },
}

return column { width = 240, children = { meter } }

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…

Push items apart

A "Fill" child takes the space its siblings leave, so a bare rect makes a spacer:

local header = row {
    width = 300,
    spacing = 8,
    children = {
        text { content = "Wi-Fi", font_size = 14, foreground = "#CDD6F4", align_v = "Center" },
        rect { width = "Fill" }, -- takes the space left over, pushing what follows to the end
        text { content = "Connected", foreground = "#A6ADC8", align_v = "Center" },
    },
}

return header

Gotchas

See also: list, rect, layout model.

Source: vocabulary, layout solver, spacing and alignment parsers, scroll.

button

A box that takes clicks, left-button drags and the wheel; no other kind has these handlers. It stacks its children like a rect, so put a row inside for an icon beside a label. Which button wins, when a click cancels and when a drag ends are on input.

A volume chip: left click mutes, the wheel changes the level.

local muted = state("muted", false)
local volume = state("volume", 0.5)

local mute_button = button {
    padding = { left = 10, right = 10, top = 6, bottom = 6 },
    radius = 8,
    background = muted:map(function(m) return m and "#F38BA8" or "#313244" end),
    on_click = function(_, which)
        if which == "left" then muted:set(not muted:get()) end
    end,
    on_wheel = function(_, steps)
        volume:set(math.max(0, math.min(1, volume:get() + steps * 0.05)))
    end,
    children = { row { spacing = 6, align_v = "Center", children = {
        icon { name = "audio-volume-high-symbolic", size = 16, foreground = "#CDD6F4", align_v = "Center" },
        text { content = volume:map(function(v) return string.format("%d%%", math.floor(v * 100 + 0.5)) end),
               align_v = "Center" },
    } } },
}

return mute_button

Properties

button takes the common and box properties, plus the ones below. rect in the callbacks is the button’s surface-local laid-out box { x, y, width, height }, before transforms.

A button with none of on_click, on_drag, on_wheel and submit = true ignores the pointer: clicks fall through to what is under it, and it sets no cursor.

How do I…

Gotchas

See also: input, rect, surfaces: popup.

Source: vocabulary, pointer dispatch, hit testing, takes_pointer.

text

One paragraph drawn in the fonts chain or a named family: labels, clocks, notification bodies. It sizes to its content, wraps and elides inside a bounded width, and mixes bold, italic, colour and links through runs. For typing, use a textfield.

Two notification cards. In the first, the title elides and the body wraps to two lines, eliding the second; the second card’s short texts fit.

local function card(icon_name, title, body)
    return row {
        width = "Fill",
        padding = 12,
        spacing = 10,
        radius = 12,
        background = "#313244",
        children = {
            icon { name = icon_name, size = 32, foreground = "#CDD6F4", align_v = "Center" },
            column { width = "Fill", align_v = "Center", spacing = 2, children = {
                text { content = title, width = "Fill", font_size = 14, elide = "End" },
                text { content = body, width = "Fill", foreground = "#A6ADC8",
                       wrap = "Word", max_lines = 2, elide = "End" },
            } },
        },
    }
end

return column { width = 340, spacing = 8, children = {
    card("dialog-information-symbolic", "Firmware update ready for the USB-C dock",
        "3 packages can be installed. Restart to finish the kernel upgrade and load the new graphics driver."),
    card("battery-caution-symbolic", "Battery low", "12% left"),
} }

The middle column is "Fill" so the texts have a bounded width; the icon keeps its 32 px.

Properties

text takes the common properties, plus:

Runs

Each run in a content array is a table:

A run also takes kind = "text", so a notification body’s text spans pass through unchanged. Drop its image spans, which have no text. A nil hole ends the array.

local body = text {
    width = 280,
    wrap = "Word",
    content = {
        { text = "Update ready. " },
        { text = "3 packages", bold = true },
        { text = " can be installed. " },
        { text = "Release notes", underline = true, color = "#89B4FA", href = "https://example.org/notes" },
    },
    on_link = function(href) process.detach("xdg-open", { href }) end,
}

Size

A text node measures its content: one line per paragraph line, 1.2 × font_size each, as wide as the widest line. wrap and elide need a box narrower than the text, so give the node a width, "Fill", or a stretched cross axis (a text in a fixed-width column wraps at the column’s width). In a content-sized row, the text measures one line and overflows instead.

How do I…

Gotchas

See also: textfield, fonts, icon.

Source: vocabulary, content parsers, measure, line height, link hit testing.

icon

A square icon from the desktop icon theme, or from a file path. Reach for it for app icons, status glyphs and tray items. Symbolic (SVG) icons take a tint. For photos and artwork at their own aspect ratio, use an image.

The focused window’s icon and title. mantle.applications maps a window’s app_id to its desktop entry, whose icon is a theme name:

local focused_icon = computed({ mantle.applications, mantle.workspaces }, function(apps, workspaces)
    local client = workspaces and workspaces.active_client
    if apps == nil or client == nil then return "" end
    local index = apps.by_app_id[client.class] or apps.by_app_id[string.lower(client.class)]
    return index and apps.entries[index].icon or ""
end)

local app_badge = row {
    spacing = 8, padding = { left = 8, right = 12, top = 6, bottom = 6 }, radius = 8, background = "#313244",
    children = {
        icon { name = focused_icon, size = 20, align_v = "Center" },
        text { content = mantle.workspaces:map(function(w)
            return w and w.active_client and w.active_client.title or ""
        end), max_width = 200, elide = "End", align_v = "Center", foreground = "#CDD6F4" },
    },
}

return app_badge

Properties

icon takes the common properties, plus:

An explicit width or height overrides that axis of the square; the icon draws at the shorter side, centred.

The theme is gtk-icon-theme-name from $XDG_CONFIG_HOME/gtk-4.0/settings.ini, else gtk-3.0/settings.ini, else hicolor. It is read once per Renderer process, so a theme change shows after a shell restart, not a reload. Files load as PNG, JPEG, WebP, GIF, SVG or SVGZ.

How do I…

Gotchas

See also: image, capabilities.

Source: vocabulary, content parsers, theme lookup, decode, icon draw.

image

A picture from a file: wallpapers, album art, avatars, thumbnails. It can decode off-thread, hold the previous picture while a new one loads, and cross-fade or run a shader between them. For theme icons, use an icon.

A wallpaper that crossfades when the path changes:

local path = state("wallpaper", "/usr/share/backgrounds/a.jpg")

return { panel {
    id = "wallpaper",
    layer = "Background",
    anchor = { top = true, bottom = true, left = true, right = true },
    width = "Fill",
    height = "Fill",
    child = image {
        id = "wallpaper_image", -- keeps the node, and so the held picture, across source changes
        source = path,
        async = true,
        transition = { duration = 600, easing = "InOutCubic" },
        width = "Fill",
        height = "Fill",
    },
} }

Properties

image takes the common properties, plus:

transition

The first picture appears without a transition. A transition shader gets everything a shader node gets, plus:

u_progress is the eased progress 0..1. A transition shader that fails to build logs once and the node falls back to the cross-dissolve.

How do I…

Round an image’s corners

An image has no radius. Put it in a box with radius and clip = "Rounded" (clip):

local cover = rect {
    width = 96,
    height = 96,
    radius = 12,
    clip = "Rounded", -- cut the image to the corners
    children = {
        image { source = "/usr/share/backgrounds/a.jpg", fit = "cover", async = true, width = "Fill", height = "Fill" },
    },
}

Gotchas

See also: icon, shader, paint, animation.

Source: vocabulary, content parsers, transition, shader stage, decode.

capture

A live preview of one output (monitor) through ext-image-copy-capture-v1, else wlr-screencopy. Reach for it for an overview, a monitor picker or a screenshot preview. Without either protocol it draws nothing and logs one warning.

A rounded preview of the first screen at up to 30 frames per second:

local first_output = mantle.screens:map(function(screens)
    return screens and screens[1] and screens[1].name or ""
end)

local preview = rect {
    width = 320,
    height = 180,
    radius = 8,
    clip = "Rounded",
    background = "#000000",
    children = {
        capture { output = first_output, live = 30, fit = "contain", width = "Fill", height = "Fill" },
    },
}

mantle.screens lists the connected outputs by connector name.

Properties

capture takes the common properties, plus:

It has no intrinsic size: without width and height it draws nothing. A hidden node or unmapped surface drops its capture and starts a fresh one when it shows again. A live capture gets a new frame only when the screen changes. A capture that fails pauses, with one warning, until the output list changes.

A region prefers wlr-screencopy, which crops at the source. Through ext-image-copy-capture-v1 the engine crops instead, and on a rotated or flipped output it cannot: it draws the whole output and logs one warning.

How do I…

Gotchas

See also: image, surfaces.

Source: vocabulary, content parsers, capture.

shader

Runs a fragment shader from the config over the node’s box: a glow, an animated gradient, a procedural pattern. It reads no textures and takes no input. To run a shader between two pictures, use an image transition.

A band that glows in over 400 ms when pulse_on turns true:

local pulse_on = state("pulse_on", false)

local glow = shader {
    width = 200,
    height = 40,
    source = mantle.config_dir .. "/shaders/glow.frag",
    progress = pulse_on:map(function(on) return on and 1 or 0 end),
    params = { tint = { 0.54, 0.71, 0.98 } },
    animate = { progress = 400 },
}

return glow

shaders/glow.frag in the config directory:

uniform vec3 tint;

void main() {
    // Distance from the horizontal centre line, 0 at the middle, 1 at the edges.
    float edge = abs(v_uv.y - 0.5) * 2.0;
    float alpha = (1.0 - edge) * u_progress;
    fragColor = vec4(tint * alpha, alpha); // premultiplied
}

Properties

shader takes the common properties, plus:

It has no intrinsic size: without width and height it draws nothing. opacity, transforms, shadow_* and content_blur apply to it.

The .frag file

GLSL ES 3.00 without the header. The engine prepends #version 300 es, precision highp float and the declarations below, then compiles the file as written. Error line numbers count from the file’s first line.

Write void main(). params never sets a uniform named u_* or mantle_*. A uniform the shader reads of any other type, such as an int or a sampler2D, refuses the whole shader.

How do I…

Gotchas

See also: image transitions, animation, paint.

Source: vocabulary, content parsers, params, shader stage, .frag reloads.

list

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

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

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

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

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

return grid

Keyed workspace buttons from a capability: workspaces cookbook.

Properties

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

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

When items rebuild

A list keeps the items it built until something that build read changes. A pass that finds nothing changed calls no itemfn and reads none of the items’ signals; it lays the kept items out again, about a third of the cost of building them. A change one item read builds that item alone; a change the list itself read builds every item, scrolled out of view or not.

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

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

How do I…

Scroll a long list

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

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

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

Gotchas