Animation

animate makes a node’s properties move to a new value instead of snapping: on a hover, a level or a toggle, as a node enters or leaves the tree, or in a loop like a spinner. A tween is one property moving from the value on screen to the value a new pass resolves. The engine runs every tween on its own surface’s compositor frames, so a panel on a 60 Hz output moves at 60 Hz beside one at 165 Hz; no Lua runs between the pass that starts a tween and its last frame.

local open = hover("tray")

return panel {
    id = "bar",
    layer = "Top",
    anchor = { top = true },
    child = row {
        hover = open,
        height = 28,
        radius = 14,
        background = "#313244",
        width = open:map(function(on) return on and 160 or 28 end),
        spacing = open:map(function(on) return on and 6 or 0 end),
        animate = { width = { duration = 200, easing = "OutCubic" }, spacing = 200 },
        children = {
            icon { name = "network-wireless-symbolic", size = 16, margin = 6 },
            icon { name = "bluetooth-active-symbolic", size = 16, margin = 6 },
        },
    },
}

How a tween starts

animate is a table from property names to entries. When a pass resolves a different value for a named property, the node moves from the value on screen to the new one. A pass that re-resolves the same value leaves a running tween alone, so an unrelated signal does not restart the motion. animate itself may be a signal (animate = shown:map(...)), but the entries inside it are plain values: a signal nested in an entry does not resolve.

What can animate

Any property the node’s kind accepts (nodes) can be named; the value’s shape decides whether it moves. The ones that do:

An image crossfading between sources uses its own transition property, not animate (image).

Range clamp

Every frame’s value is clamped to the property’s range, which catches overshoot from Back, Elastic, a Bezier with y outside [0, 1], or a spring. Only margin, translate, rotate, progress, shadow_offset and shadow_spread may go negative. padding, spacing and icon size have no range as plain values but tween within [0, 8192].

Layout cost

Slide with translate and grow on hover with scale when surrounding nodes should stay put. Both skip layout; width and margin lay out the surface on every animation frame.

Entry keys

An entry is a bare number (a duration in ms with the default easing) or a table. Every entry picks one of three motions: eased (duration), keyframes (keyframes + duration) or spring (spring).

A duration or delay that is not a number ("200") is refused rather than read as absent.

Easing names. A name is case-sensitive; an unknown one is refused with the list.

In starts slow, Out ends slow, InOut does both. Back and Elastic overshoot, and the range clamp above catches it; Bounce stays inside the range.

The same 600 ms width change under six easings. OutBack passes the target and comes back:

local go = state("go", false)

local function race(label, easing)
    return row {
        spacing = 8,
        children = {
            text { content = label, width = 80, font_size = 12, foreground = "#a6adc8" },
            rect {
                height = 12,
                radius = 6,
                background = "#89b4fa",
                width = go:map(function(on) return on and 200 or 12 end),
                animate = { width = { duration = 600, easing = easing } },
            },
        },
    }
end

return column {
    spacing = 6,
    children = {
        race("Linear", "Linear"),
        race("InOutQuad", "InOutQuad"),
        race("OutCubic", "OutCubic"),
        race("OutBack", "OutBack"),
        race("OutBounce", "OutBounce"),
        race("steps = 4", { steps = 4 }),
    },
}

Spring

A spring has no duration: stiffness and damping decide how it settles. Use one for a target that changes mid-flight, like a held volume key or a pointer-following highlight. The spring carries its velocity into the new motion; an eased tween restarts from a standstill and lags behind. A spring that replaces an eased tween starts at rest.

There is no mass: it would only rescale the other two. A spring stops within a thousandth of its travel and never runs longer than 60 s.

The same translate change on three springs of stiffness = 400, where critical damping is 40. The underdamped knob passes the others’ resting point and swings back:

local go = state("go", false)

local function knob(label, damping)
    return row {
        spacing = 8,
        children = {
            text { content = label, width = 130, font_size = 12, foreground = "#a6adc8" },
            rect {
                width = 176,
                height = 16,
                radius = 8,
                background = "#313244",
                children = {
                    rect {
                        width = 16,
                        height = 16,
                        radius = 8,
                        background = "#cba6f7",
                        translate = go:map(function(on) return { x = on and 100 or 0 } end),
                        animate = { translate = { spring = { stiffness = 400, damping = damping } } },
                    },
                },
            },
        },
    }
end

return column {
    spacing = 8,
    children = {
        knob("damping = 12, rings", 12),
        knob("damping = 40, critical", 40),
        knob("damping = 120, crawls", 120),
    },
}

Keyframes

A keyframes entry walks a list of values instead of easing to the resolved one. While it runs, it owns the property: the value the pass resolves is ignored.

To replay a finished run, take the entry away and put it back. pulse does both in one expression: it reads true for a window after its source changes.

local taps = state("taps", 0)
-- Three 120 ms segments: `duration` times each one, so the run takes 360 ms.
local BOUNCE = { scale = { duration = 120, easing = "OutQuad", keyframes = { 1, 1.25, 0.9, 1 } } }

return panel {
    id = "bar",
    layer = "Top",
    anchor = { top = true },
    padding = 4, -- room for the overshoot: a scaled node paints past its box
    child = button {
        width = 32,
        height = 32,
        radius = 8,
        background = "#313244",
        on_click = function() taps:set(taps:get() + 1) end,
        -- pulse is true for 400 ms after each tap: the entry appears, plays once, then goes.
        animate = pulse(taps, 400):map(function(on) return on and BOUNCE or {} end),
        children = { icon { name = "starred-symbolic", size = 16, foreground = "#CDD6F4", align_h = "Center", align_v = "Center" } },
    },
}

An endless spinner needs no signal. A hidden spinner stops requesting frames by itself:

local busy = state("busy", true)
local SPIN = { rotate = { duration = 1000, easing = "Linear", keyframes = { 0, 360 }, loops = "Infinite" } }

return panel {
    id = "bar",
    layer = "Top",
    anchor = { top = true },
    padding = 4, -- room for the corners as it turns
    child = icon {
        name = "view-refresh-symbolic",
        size = 16,
        foreground = "#CDD6F4",
        visible = busy,
        animate = SPIN,
    },
}

Exit

animate.exit animates a child after its parent stops returning it: a notification removed from a list, or a card dropped from children. The block holds one timing for every property, and the values to ease to.

exit = { duration = 150, easing = "InQuad", opacity = 0, translate = { y = 16 } }

Hiding a surface skips the exit, so drop the child from children and hold the surface open with delay until the exit has played. The card below slides up and fades in on show; the shot plays the hide, down and out over 150 ms:

local shown = state("osd_shown", false)
-- Keep the surface mapped 150 ms past `shown`, so the card's exit can play.
local mapped = computed({ shown, delay(shown, 150) }, function(now, was)
    return now == true or was == true
end)

local card = rect {
    width = 240,
    height = 48,
    radius = 12,
    background = "#1e1e2ee6",
    opacity = 1,
    translate = { y = 0 },
    children = { text { content = "Volume 42%", align_h = "Center", align_v = "Center", foreground = "#CDD6F4" } },
    animate = {
        opacity = { duration = 200, from = 0 },
        translate = { duration = 200, easing = "OutCubic", from = { y = 16 } },
        exit = { duration = 150, easing = "InQuad", opacity = 0, translate = { y = 16 } },
    },
}

return panel {
    id = "osd",
    layer = "Overlay",
    anchor = { bottom = true },
    width = 240,
    height = 64, -- room for the exit's 16 px slide
    visible = mapped,
    child = column {
        height = "Fill",
        children = shown:map(function(on) return on and { card } or {} end),
    },
}

How do I…

Fade a tooltip popup in and out

A popup closing skips the exit, so switch the card out of children and let delay hold the popup open while it fades.

local over = hover("clock")
-- Stay mapped 120 ms after the pointer leaves, so the card's exit can play.
local mapped = computed({ over, delay(over, 120) }, function(now, was)
    return now == true or was == true
end)

local card = rect {
    width = 180,
    height = 32,
    radius = 6,
    background = "#1e1e2e",
    opacity = 1,
    animate = { opacity = { duration = 120, from = 0 }, exit = { duration = 120, opacity = 0 } },
    children = { text { content = "Thursday, 24 September", padding = 8 } },
}

return {
    panel { id = "bar", layer = "Top", anchor = { top = true }, child = text { content = "12:30", padding = 8, hover = over } },
    popup {
        id = "clock_tooltip",
        parent = "bar",
        anchor_rect = hover_rect("clock"),
        anchor = "Bottom",
        gravity = "Bottom",
        grab = false,
        visible = mapped,
        child = rect {
            children = over:map(function(on) return on and { card } or {} end),
        },
    },
}

Stagger a list’s entrance

Give each item a delay that grows with its index. delay holds the from value, so a card waits invisible for its turn.

local go = state("go", false)
local titles = { "Battery low", "Update ready", "Download complete" }

local function card(index, title)
    local wait = (index - 1) * 80
    return rect {
        width = 200,
        padding = 10,
        radius = 8,
        background = "#1e1e2e",
        opacity = 1,
        translate = { x = 0 },
        animate = {
            opacity = { duration = 200, delay = wait, from = 0 },
            translate = { duration = 200, delay = wait, easing = "OutCubic", from = { x = -24 } },
        },
        children = { text { content = title, foreground = "#cdd6f4" } },
    }
end

return column {
    spacing = 6,
    children = go:map(function(on)
        local cards = {}
        for index, title in ipairs(on and titles or {}) do
            cards[index] = card(index, title)
        end
        return cards
    end),
}

Slide a notification out

Removing an item from a keyed list makes it leave. The remaining cards close up at once; only the leaving one moves.

local notes = state("notes", { "Battery low", "Update ready", "Download complete" })

local function dismiss(title)
    local kept = {}
    for _, other in ipairs(notes:get()) do
        if other ~= title then kept[#kept + 1] = other end
    end
    notes:set(kept)
end

local function card(title)
    return button {
        width = 280,
        padding = 12,
        radius = 12,
        background = "#1e1e2e",
        border_width = 1,
        border_color = "#45475a",
        on_click = function() dismiss(title) end,
        animate = { exit = { duration = 200, easing = "InCubic", opacity = 0, translate = { x = 300 } } },
        children = { text { content = title, foreground = "#cdd6f4" } },
    }
end

return panel {
    id = "notifications",
    layer = "Overlay",
    anchor = { top = true, right = true },
    width = 300,
    height = 400,
    child = list { spacing = 8, source = notes, itemfn = card, key = function(title) return title end },
}

Gotchas

See also: signals (pulse, delay, hover), nodes (properties and identity), input (hover and clicks that drive motion), paint (what the painted properties draw).

Source: animate, easing, spring, keyframes, leaving nodes, range clamps.