Tags and attributes¶

Every tag and attribute the .lmn markup parser accepts, what it does, and what it defaults to. For the style surface see CSS; for the task-level introduction see Writing markup.

Markup is XML-shaped. Every tag closes (<tile/> or <tile></tile>), attribute values are double-quoted, and a single element wraps the document (<root> by convention). An unknown tag is a compile error. An unknown attribute is dropped with a warning, so forward-compatible markup still parses and a typo is still reported. Attributes on a custom widget tag are exempt: the widget reads its own props out of them.

Element nesting is capped at 32 levels; a template instantiating other templates is capped at 64 levels of nesting.

Value forms¶

Boolean attributes¶

Every boolean attribute reads the same set of values:

Matching is case-sensitive, so True warns.

Text content and interpolation¶

An element's text child becomes its text: <label>Hello</label> is the same as <label text="Hello"/>. An explicit text attribute wins, and only the first non-empty text child is read.

{...} placeholders are substituted in text, placeholder, src, id, class, style, and drag-payload:

Bare {name} still works; the compiler emits an informational lint suggesting the explicit form.

A placeholder is resolved when the tree it belongs to is built, against the signals as they stand then; a <for> row is built per record and reads the signals then. One naming a signal nothing has set stays in the string as the braces the author wrote, so a typo reads as a typo. A {row.field} the record does not carry is the exception: it resolves to an empty string and is reported, because the record is what says which fields there are.

A {k} placeholder inside a <template> body reads the parameter k, and falls back to the global signal k when no use site binds it. See Composition.

Common attributes¶

These apply to any element unless the entry says otherwise.

Identity¶

Sizing¶

Spacing¶

Layout¶

Flex direction comes from the tag, not an attribute: <row> lays out horizontally, <column> vertically. Use CSS flex-direction to change it, including the reverse variants.

overflow: scroll on any element makes it a live scroll container, the same as <scroll>.

An element's own text lays out as an item of its own, sized to the words, so justify places it along the main axis the same way it places a child: justify="center" on a <button> centres its label. It applies on a horizontal main axis only, and an authored text-align wins where both are set.

Colour and paint¶

The markup shadow attribute takes one shadow. Stacked shadows are a CSS feature.

Typography¶

wrap="ellipsis" elides overflowing single-line text with a trailing .... It is the markup spelling of CSS text-overflow: ellipsis.

Text input paint¶

Only meaningful on <input> and <textarea>.

Scrolling¶

sensitivity and inertia apply to scroll containers. The scrollbar-* attributes style the overlay scrollbar.

Setting scroll="x" also flips a column-defaulted container to a row so children stack left to right.

Interaction and drag and drop¶

An element receives the pointer when it is focusable (it has a tab-index, which the controls and <a href> carry by default), when it scrolls, or when it paints a background. Painting is not required: a <button> with no bg in markup, in your CSS, or in a skin still hovers, presses, and clicks over its own rect. Where several targets overlap, the innermost one takes the event.

Binding¶

Values name a signal, with or without a leading $.

bind-text, bind-checked, and bind-value share one slot, so an element binds at most one of them. bind-disabled and bind-scroll are independent and may be combined with the others.

bind-text, bind-checked, and bind-value also accept $self.<field> and $parent.<field> to read a per-entity property bag instead of a global signal. bind-disabled and bind-scroll accept named signals only.

No bind-* accepts $arg.<name>, the form that names a template argument; it is refused with an error. An argument is substituted once, when the instance is created, so a value that changes while the app runs belongs in a signal the body binds to.

A widget seeds its bound signal from the authored value on first spawn if the signal is not already set.

Built-in sizing floors¶

An always-on stylesheet applies these beneath any skin and beneath your CSS, so a bare app still has usable controls. Any rule of yours wins.

• root, title-bar: width: 100%; title-bar is 32 px tall.
• button: min-height: 36.
• input, textarea: min-height: 24, min-width: 160.
• toggle: height: 36, min-width: 96.
• switch: height: 28, min-width: 52 when neither width nor min-width is set.
• slider: height: 36, min-width: 160.
• checkbox, radio: min-height: 24.
• progress: width: 100%, height: 6.
• .checkbox-box, .radio-dot: 18 by 18.

<input> and <textarea> also default to overflow: hidden on both axes unless you author overflow, overflow-x, or overflow-y.

Containers¶

<root>¶

The document element. Lays out as a column and fills the window.

In a multi-page app, skin and frameless are read from the home page only. Every other attribute on a page's <root> styles that page. See multi-page apps.

<column>¶

Stacks children vertically.

<row>¶

Stacks children horizontally.

<tile>¶

A plain box with no layout defaults. The usual choice for a styled surface.

<div>¶

Identical to <tile>. Both are boxes with no per-tag defaults.

<spacer>¶

A box that defaults to grow="1", so it absorbs the remaining space on the main axis and pushes its neighbours apart.

<scroll>¶

A scroll container. Defaults to a vertical column scroller; scroll="x" switches to a horizontal row scroller and scroll="both" enables both axes. Accepts sensitivity, inertia, bind-scroll, and the scrollbar-* attributes. A scroll container is a layout boundary.

Its direct children default to shrink: 0, so content taller (or wider) than the container keeps its own size and scrolls instead of being squeezed to fit. Write shrink: 1 on a child to opt back in.

<overlay>¶

Floats out of normal flow: position: absolute with all four insets at 0, so it covers its parent's box. It is not reparented; it stays where it is written, which is what a dropdown anchored to its trigger wants. Lays out as a column. Use it for backdrops, dropdowns, and floating panels.

An <overlay> under a parent that is content-sized and has no in-flow children covers nothing, because that parent measures zero. See Positioning.

Text and media¶

<label>¶

Text. Carries no layout defaults of its own; the text attributes above control its appearance.

<a>¶

An anchor. Clicking it navigates the app to another page. An anchor takes the pointer with or without a background, and takes focus when clicked, but it is not in the Tab chain unless you give it tab-index="0".

See Pages.

<image>¶

Loads and draws an image file.

On the web an <image> is emitted as an <img> carrying the size of the file the build copied, decoding="async", and loading="lazy" on every image after the first one on the page. See the web target.

<canvas>¶

A surface a script draws on: paths, rectangles, arcs, text, and pixel buffers. The drawing functions come from the canvas namespace; see Rhai, Lua, or candela for the catalog.

The tag comes from the lumen-canvas module, so an app declares it before it can write one:

[dependencies]
lumen-canvas = { bundled = true, tags = ["canvas"] }

width and height say what coordinates a script draws in. They are also the element's default size, and layout is free to give it a different box: flex-grow, a percentage width, or a min or max size all do. When the box differs, the drawing is scaled onto it, so one script draws the same picture at any size. An axis with no declaration draws in 300 units across or 150 down, which is what an HTML canvas has always defaulted to.

Setting width in CSS changes the drawing space, because a width in CSS and a width in markup are the same declaration by the time the element exists. That is a difference from the HTML canvas, where the attribute is the drawing space and CSS scales it. The declaration is read once, when the element is first laid out, so a later theme or media change does not resize the drawing space under a script that is mid-drawing.

The drawing space is the element's, so a script reads it once the element is mounted: on_ready, not on_start. Drawing from on_start works either way; the calls are kept and appear when the element does.

A canvas is retained. What a script draws stays until canvas::clear, or until canvas::resize, which empties it the same way writing width on an HTML canvas does. Drawing outside the element's box is clipped.

Not here yet: clear_rect, clipping, blend and composite modes, gradients, patterns, shadows, measure_text, stroke_text, text alignment and baselines, ellipse and arc_to, dashed strokes, image smoothing, drawing an image file or another canvas directly, reading a composed canvas back, and a per-canvas device pixel ratio. Canvas does not exist on the web target, which refuses [dependencies] outright.

Controls¶

<button>¶

A focusable, clickable box. Focusable by default (tab-index="0").

A button holds its label itself rather than in a child element, so justify="center" is what centres the text.

<input>¶

A single-line text field. Focusable by default. Starts with an empty buffer, so a text child is ignored; use text for an initial value.

min and max also feed validation on <input> and <textarea>.

<textarea>¶

Same as <input> with multiline defaulting to true.

<toggle>¶

A checkbox-style boolean control rendered as a track with a knob. Focusable by default.

Style the checked track with :checked { bg: ... } and the knob with knob-color and knob-inset.

<switch>¶

The same boolean control in switch presentation: a narrower pill track with a sliding thumb. It reports itself to assistive technology as a switch. Same attributes as <toggle>.

<slider>¶

A draggable value control. Focusable by default.

Arrow keys move by one step, Page Up and Page Down by ten. Style the thumb with knob-color and thumb-size.

A click or a drag lands on the same positions the arrow keys reach: the value is min plus a whole number of steps. A range that is not a whole number of steps stops on the last step that fits, so min="0" max="100" step="30" tops out at 90.

<checkbox>¶

A row containing an indicator box and a caption. Focusable by default. The parser synthesizes the two parts, so CSS can reach them as .checkbox-box and .checkbox-label. On the web the indicator is the browser's own control and carries the same class, so one rule styles both targets.

Defaults to align="center" and gap="8" when you do not set them.

<radio>¶

One member of an exclusive group. The group's selected value lives in a signal. Synthesized parts are .radio-dot and .radio-label; on the web the dot is the browser's own control under the same class.

Radios start at tab-index="-1"; on the desktop exactly one member of each group is promoted at runtime, so Tab enters and leaves the group as a unit and arrow keys move within it. Nothing promotes a member on the web, where the group is reachable with a pointer only.

<progress>¶

A non-interactive progress track. Lays out as a row and fills its container's width. The parser synthesizes a .progress-fill child.

<dropdown> and <option>¶

A combobox. The parser expands it into a header button plus a floating options panel; the panel is dismissed by clicking outside it and flips above the trigger near the bottom of the window.

The tag stays on the box those parts sit in, so width, min-width, padding, bg and a dropdown rule in a stylesheet size and paint the control the way they do any other widget. The generated elements carry the classes dropdown-button for the closed face, dropdown-panel for the floating list, and dropdown-option for a row in it. The face fills the box, so sizing the <dropdown> sizes the whole control; the face's height and an option row's are theme metrics, so restyle those classes to change them.

<dropdown> requires bind-value. Its children must all be <option>.

The closed header reads the selected option's label. The signal holds that option's value, which is what your script reads and what a click writes, so the two differ whenever an option carries a label of its own. A value no option declares is shown as it stands.

The first <option> seeds the signal, so the dropdown opens on a real selection. Add placeholder to start unselected instead. A value your script writes first always wins over the seed.

The closed dropdown handles Up and Down to step the value, Alt+Down, Space, or Enter to open, and type-ahead.

<option> outside a <dropdown> is an error.

<tabs> and <tab>¶

A tabbed container. The parser expands it into a button strip plus one body per tab; bodies are mounted once and shown or hidden, so focus and scroll state survive switching.

<tabs> requires bind-value. Its children must all be <tab>.

The first <tab> seeds the signal, so it is active at startup. The generated elements carry the classes tabs, tab-strip, and tab-btn.

<tab> outside <tabs> is an error.

<date-picker> and <time-picker>¶

A validated text field for a date or a time. Each expands to an <input> with a built-in pattern and the class date-picker or time-picker.

The built-in check matches the placeholder: YYYY-MM-DD with month 01-12 and day 01-31 for a date, HH:MM with hour 00-23 and minute 00-59 for a time. Digits and separators must sit in those positions, ignoring surrounding whitespace. It is a shape check, not a calendar check, so 2026-02-31 passes.

Validity lands in the valid:<id> signal like any other validated field, so give the picker an id to read the result.

Structure¶

<for>¶

Repeats its children once per item of an array signal. Lays out as a column.

Inside the body, {row.field} reads the current record and {$index} the row index. A virtualized <for> is forced to full width so its rows have a reference box.

<if>¶

Mounts its children conditionally.

<template>, <use>, and <slot>¶

<template name="Card">...</template> declares a reusable subtree. Instantiate it as <Card k="v"/> or <use template="Card" k="v"/>. Every {k} placeholder in the body is a parameter, and takes the value the use site binds to k. Attributes on the <template> tag itself (other than name) are defaults for the parameters a use site leaves unbound; a parameter with neither reads the global signal k. Placeholders resolve in attribute values and text, not in tag names.

<slot/> inside a template body is replaced with the content of the use site. When the use site has none, the slot falls back to its default="..." attribute and then to its own inner content.

Giving the use site an id prefixes every id inside the instantiated body with it, so multiple instances keep distinct ids. Templates may instantiate other templates, up to 64 levels; a cycle is an error.

A declaration is visible to the whole file, wherever it sits in it, to any file that includes that file, and app-wide in a multi-page app.

The name of a candela component instantiates the same way: <Home name="bob"/> takes the lmn! block the function Home returns. Any component can be named this way. Where the block is the function's whole body and reads only its parameters, the build puts it in the tree outright; where the function works a value out or picks between blocks, the build leaves a marker there and the runtime fills it by calling the function on the first tick. Component names and <template> names share one namespace, and two declarations claiming one name are an error. See composition.

<include>¶

<include src="../parts/header.lmn"/> splices another file's markup in place. Paths are relative to the including file. Includes resolve before parsing, they nest, and a cycle is an error. Included files are watched for hot reload.

<script>¶

Collects script source. It is not a layout element and can appear anywhere in the tree.

Without src, the tag's text content is the script. Each src file runs under the host its extension names (.cdl, .rhai, .lua); sources of one language are concatenated into one program. A tag with a body has no extension to read and joins the app's one external language, or candela when there is not exactly one. [script] engine in lumen.toml overrides all of it and puts every source on one host. See Scripting.

Shell¶

<menubar>¶

Declares the OS-native application menu. At most one per document, as a direct child of <root>. It is removed from the layout tree. Its children must be <menu label="...">.

<menu>, <menuitem>, and <separator>¶

Inside <menubar>, <menu label> is a top-level menu and its children are <menuitem> and <separator>.

Outside a menubar, <menu id="m"> is an in-window popup panel toggled by the signal __menu_open:m. It expands to a floating panel of buttons with the classes menu-panel, menu-item, and menu-separator, and it dismisses on an outside click.

<menuitem> and <separator> outside a menu are an error.

<dialog>¶

A modal overlay: absolutely positioned over its parent's box, centered, with its children as content. Focus is trapped inside it while it is open. Write it as a direct child of <root>, which is what makes it cover the window; under a content-sized parent it covers nothing (see Positioning).

Inside a dialog, autofocus picks the element that takes focus on open, and <button default="true"> is the default button.

<tooltip>¶

Wraps exactly one trigger element and shows a popup after the pointer dwells on it. The wrapper collapses at parse time, so CSS selectors apply to the trigger, not to <tooltip>.

Wrapping zero or more than one element is an error.

<title-bar>¶

A title-bar region for frameless windows. Lays out as a row, full width, 32 px tall.

Pair it with <root frameless="true">.

Custom tags¶

A Rust plugin can register additional tags, which then parse like built-in ones. See Authoring plugins.