Shell Lua API

shady-shell draws whatever its Lua config describes. The default UI (bar, Quick Settings, task menu, launcher) is itself a config: shell/default.lua. Read it alongside this page.

Config file

The shell loads the first of:

1. $SHADY_SHELL_CONFIG
2. $XDG_CONFIG_HOME/shady/shell.lua (or ~/.config/shady/shell.lua)
3. shell/default.lua from the data directory ($SHADY_SHELL_DATA_DIR overrides it)

If your config fails to load at startup, the shell logs the error and falls back to the default. Edits are picked up live: saving any .lua file in the config’s directory reloads the config in a fresh Lua state. If the new version fails, the error is logged and the running UI stays as it was. require finds modules next to the config and in the data directory.

To keep the default UI and change a few things, start your config with:

dofile(shell.data_dir .. "/default.lua")

Views

Every surface has a view function that returns a widget tree. The shell calls it whenever the surface is repainted: when the compositor’s state changes, a polled value changes, the clock ticks, the pointer moves onto something with an id, or you call shell.redraw(). Views should only read state and build widgets; they may not open or close popups.

The first argument is a context table:

Popups receive the table passed to shell.open as a second argument.

shell.bar{...}

A bar on every output, or on the outputs listed.

shell.bar {
    name = "top",                 -- required, unique
    edge = "top",                 -- "top" or "bottom"
    size = 38,                    -- height in logical pixels
    exclusive = true,             -- reserve space so windows avoid it
    layer = "top",                -- background | bottom | top | overlay
    outputs = { "DP-1" },         -- default: all outputs
    view = function(ctx) return shell.row { ... } end,
}

shell.popup{...}

A surface that is opened and closed on demand.

shell.popup {
    name = "quick",
    anchor = { "top", "right" },  -- edges; none centres it
    margin = { top = 42, right = 8 },
    width = 250,                  -- omit width/height to fit the content
    keyboard = "none",            -- none | exclusive | on_demand
    persistent = false,           -- keep it open, like a bar
    outputs = nil,                -- "all": persistent on every output, one each
    fill = false,                 -- cover the whole output (anchors and size ignored)
    exclusive = 0,                -- pixels to reserve along its anchored edge
    input = "all",                -- or "widgets": take the pointer only over interactive widgets
    text_input = false,           -- take text from input methods (Hangul, Japanese, ...)
    layer = "overlay",
    view = function(ctx, args) ... end,
    on_key = function(key, text, args) ... end,
}

With text_input = true (and a keyboard mode) the popup takes text from the input method, through text-input-v3: what is still being composed is ctx.preedit in the view, and committed text arrives in on_key with an empty key name, like typed text. Mark the widget where text goes with caret = true, so the input method places its candidate window next to it.

Without width or height the popup takes its content’s natural size and follows it as the content changes. on_key receives the xkb key name ("Escape", "Return", "Up", "BackSpace", "a") and the text it types ("" for none).

A fill popup covers its output: a full-screen launcher, or with layer = "background" a wallpaper. Its view gets the output’s size as ctx.width and ctx.height. Background and bottom layer surfaces are drawn behind the windows, also in spatial mode, and only take the pointer where no window is.

With input = "widgets" the surface takes the pointer only over widgets that react to it (on_click, on_drag, on_scroll, id or hover); everywhere else clicks fall through to the windows or the desktop below. This makes a full-screen fill layer usable as a desktop with a few clickable things on it.

A persistent popup is opened by the shell itself as soon as an output is ready, stays on one output, and moves to another when its output goes away (a monitor unplugged, a VT switch). The greeter’s login card is one (GREETER.md).

With outputs = "all" a popup is persistent on every output instead: one copy per output, following hotplug, each getting its own output as ctx.output. Wallpapers, docks and desktop widgets use it. shell.open, shell.close and shell.is_open are meant for popups that come and go, not for these.

Opening popups

Widgets

Widgets are tables; these constructors fill in type:

Children may contain false (skipped, so cond and widget or false works) and plain lists of widgets (spliced in, so loops can build them).

Layout

Containers lay children out along one axis, like a simplified flexbox.

In a stack (direction = "stack") every child gets the whole inner area to itself. A child with left, top, right or bottom is pinned that far from the edge (both of a pair: stretched between them, e.g. a full-size backdrop with all four 0); otherwise justify places it horizontally and align vertically. Later children are drawn over earlier ones.

Style

Colours are "#RGB", "#RRGGBB", "#RRGGBBAA" or {r, g, b, a} in 0..1.

scale, rotate and translate move only what is drawn; layout and hit-testing use the untransformed box.

Animation

Views return a new tree on every repaint; an animated widget is matched with its previous self and springs from its old look to its new one. Position and size (relative to the parent, so children ride along with a moving parent), background (gradients included), border, color, opacity, scale, rotate, translate and shadow all animate.

enter, exit and hover animate with "smooth" without animate. key is for widgets that need a stable identity but must not become ctx.hovered targets, such as a dot that comes and goes inside a pill.

shell.row {
    id = "clock", animate = "snappy",
    background = open and t.accent_deep or a(WHITE, 0.03),  -- fades
    enter = { opacity = 0, translate = { 0, -8 } },          -- slides in
}

While springs move, the shell repaints on every frame from the last tree without running the view; when they settle it goes back to repainting only on changes.

Interaction

info holds the widget’s box (x, y, width, height), the pointer inside it (px, py), the same as 0..1 fractions of its size (fx, fy, clamped) and the output. The deepest widget with the handler under the pointer gets the event; a left press goes to on_drag before on_click.

shell.stack {
    width = 200, height = 24,
    on_drag = function(info) set_volume(info.fx * 100) end,
    on_scroll = function(dy) set_volume(volume - dy / 2) end,
    ...
}

Compositor state and actions

State comes from the compositor over the shady-shell-v1 protocol.

Window arguments may also be the window tables themselves.

Other data

shell.poll and shell.listen start their command the first time a view asks for it and keep it running for as long as the config is loaded. Any change in their value repaints the views. Together with shadyctl subscribe (see IPC_API.md) they cover most status widgets without native code:

local volume = shell.poll("wpctl get-volume @DEFAULT_AUDIO_SINK@", 2000)
local battery = shell.poll("cat /sys/class/power_supply/BAT0/capacity", 30000)

Notifications

The shell can be the desktop’s notification server (org.freedesktop.Notifications, spec 1.2, over sd-bus). A config asks for it; it keeps running across reloads. If another daemon owns the name, it returns false and the shell leaves that daemon alone.

Every change (one arrives, expires, closes or is replaced) emits the notifications event and repaints the views. Active notifications are the ones to show as toasts; the default UI opens a toasts popup while there are any:

shell.notification_server()
shell.on("notifications", function()
    local any = false
    for _, n in ipairs(shell.notifications()) do any = any or n.active end
    if any ~= shell.is_open("toasts") then
        if any then shell.open("toasts") else shell.close("toasts") end
    end
end)

Events

shell.on(name, fn) registers a handler:

Shader effects

With the GL renderer (the default), any bar, popup or widget can be drawn through a GLSL ES 1.0 fragment shader. Effects are skipped, with one log line, on the wl_shm renderer.

shell.bar {
    name = "top",
    shader = shell.shader("shaders/aurora.frag"),
    uniforms = { strength = 0.55, accent = shell.theme.accent },
    view = function(ctx)
        return shell.row {
            shell.row { shader = shell.shader("shaders/glow.frag"),
                        uniforms = { color = "#28e6ff", strength = 0.9 }, radius = 9, ... },
        }
    end,
}

• shell.shader(path) finds a fragment shader by absolute path, next to the config, or in the data directory, which ships shaders/aurora.frag and shaders/glow.frag. shell/examples/aurora.lua puts both on the default UI.
• A surface shader (shader on shell.bar/shell.popup) covers the whole surface. Its uniforms may be a table or a function returning one, called on every repaint.
• A widget shader (shader on a widget) covers the widget’s rectangle after the surface is drawn. Its uniforms is a table.
• Both receive the surface’s cairo drawing as u_tex, so they can keep, tint, distort or replace it. A shader that fails to compile is logged and the content is drawn as if it had none.

Shaders declare only the uniforms they use. The shell supplies:

and two varyings: v_uv, the surface position to sample u_tex at, and v_local, running 0..1 across the effect (both with y pointing down). A precision statement is added for you.

Lua uniforms become u_<name>: a number is a float, a colour a vec4, and a list of 1–4 numbers a float to vec4.

Output premultiplied colour, like u_tex. A shader that declares u_time is animated: the shell composites it every frame from the last drawing, without running any view, so an animated bar costs GPU time but almost no CPU. Shader files are watched with the config, and saving one reloads it.

Compositor values

shell.compositor_value(key[, fallback]) returns a value the compositor published, from its Lua (shady.publish) or a compositor plugin (publish_value), and views that read it repaint when it changes. The shell follows them over the IPC socket (“, set for programs the compositor starts) and reconnects if the compositor restarts it. This is how a bar follows a rice’s state, such as the current hour or palette:

local accent = shell.compositor_value("afterglow.accent", shell.theme.accent)

Native plugins

Plugins outlive config reloads. Writing them is covered in SHELL_PLUGIN_API.md; shell/examples/sysinfo.lua adds a CPU graph to the default bar with the bundled sysinfo plugin, through the default UI’s shell.options.bar_extra hook.

Frosted glass

Shader effects in the shell cannot see what is behind a surface. The compositor can: in spatial mode, shady.layer_effect(name, { blur = 18 }) in the compositor’s init.lua blurs the scene behind every layer surface whose namespace is name. A bar’s or popup’s namespace is its name here ("shady-shell", "quick", "menu", "launcher" in the default UI). Glass shows through translucent backgrounds, so pair it with shell/examples/glass.lua, which sets shell.options.bar_opacity and panel_opacity. See LUA_API.md for the options.

3D placement

The compositor can also tilt, turn or recede any layer surface in spatial mode, with clicks mapped to where it is drawn: shady.layer_transform("shady-shell", { tilt = -30, depth = 40 }) in the compositor’s init.lua leans the default bar back from its top edge. Like layer_effect, it selects surfaces by namespace. See LUA_API.md.