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 sets weight and italic style for the whole node, 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.

These node-level styles change line spacing, character spacing, and the selected font face:

return column { width = 320, padding = 16, spacing = 10, radius = 12,
    background = "#313244", children = {
    text { content = "Default: One line\nSecond line", font_size = 16 },
    text { content = "Taller lines: One line\nSecond line", font_size = 16,
           line_height = 1.7, foreground = "#A6E3A1" },
    text { content = "Wide letters", font_size = 16, letter_spacing = 3,
           foreground = "#89B4FA" },
    text { content = "Bold italic", font_size = 16, font_weight = 700,
           italic = true, foreground = "#F9E2AF" },
} }

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,
}

return body

Variable fonts

font_variations sets a variable font’s axes, as CSS font-variation-settings does. Keys are 4-character tags and case matters: registered axes are lower case (wght, wdth, opsz, slnt), a font’s own axes upper case (FILL, GRAD).

local starred = state("starred", false)
local star = text {
    font = "Material Symbols Rounded",
    font_size = 24,
    content = "\u{e838}",
    font_variations = starred:map(function(on) return { FILL = on and 1 or 0, GRAD = 0, opsz = 24 } end),
}

Size

A text node measures its content: one line per paragraph line, line_height × font_size each, as wide as the widest line. The default ratio is 1.2. letter_spacing changes both glyph placement and the width used for wrapping. 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.

line_height sets layout only: glyph ink that runs past a tight line box, such as a descender, paints outside it. Only the node’s width and an ancestor’s clip cut it.

Bind an elided(name) signal as elided to detect content removed by elide or max_lines. Wrapping alone keeps it false. Elision cuts at grapheme boundaries, preserving combining marks and emoji sequences. elide = "start" keeps the end of the line and "middle" keeps both ends, which suits file names whose extension matters; the end side takes the odd grapheme. Both cut in logical order, so “start” is the start of the string even in right-to-left text, and both act as "end" under wrap. With wrap = "word", max_lines = N and elide = "end", the preview keeps the first N shaped lines and adds … to the last retained line. It shortens that line only as needed to fit the ellipsis; it never merges content from later lines into the preview.

How do I…

Gotchas

See also: textfield, fonts, icon.

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