Elements
Generated from spec/language/elements.yaml, the file the analyzer checks pages against and the web emitter maps from.
Elements
<screen>
The root of a page. Fills the available space and scrolls when its content is taller.
Stability: experimental · On the web: <main>
| Attribute | Means | Written as |
|---|---|---|
title | The title shown in the navigation header and the browser tab, as text or as an expression that the title follows. | either |
description | What the page is about, in a sentence or two, for search engines and link previews (decision 0162). On the web it is the page's meta description; a phone has no use for it. Written as text. | text |
<view>
A container. Every container is a stack; add row to lay children out sideways.
Stability: experimental · Events: on:press, on:longpress, on:swipe, on:key · On the web: <div>
| Attribute | Means | Written as |
|---|---|---|
disabled | While true, tells assistive technology the view is unavailable, such as a row that cannot be opened. It changes nothing else; pair it with a dimmed look. | either |
<text>
A run of text.
Stability: experimental · On the web: <span>
| Attribute | Means | Written as |
|---|---|---|
level | With role="heading", how deep the heading is, from "1" (the page's own heading) to "6". On the web a levelled heading is written as h1 to h6, which search engines and screen readers read as the page's outline (decision 0162); without a level a heading is read as level 2. Written as text. | text |
<button>
A pressable control. Inside a form it does not send the form unless marked submit.
Stability: experimental · Events: on:press, on:longpress, on:focus, on:blur, on:key · On the web: <button>
| Attribute | Means | Written as |
|---|---|---|
submit | Makes pressing the button send the form it is in. | none |
disabled | While true, the button cannot be pressed or focused, and disabled: utilities apply. | either |
<image>
An image, sized by its styles and decoded off the UI thread. Each address is fetched and decoded once for the whole app, however many images show it (decision 0038). It needs alt, or decorative when it only decorates (E0160).
Stability: experimental · Requires src · Events: on:load, on:error, on:dismiss · On the web: <img>
| Attribute | Means | Written as |
|---|---|---|
src | The image address. | either |
alt | What the image shows, for screen readers. Required unless decorative. | either |
decorative | The image adds nothing a screen reader user needs, so it is hidden from them. Written decorative={condition}, it follows the condition: while it holds, the image has no description; decorative={false} is not decorative. | either |
placeholder | The colour that fills the image's box while it loads: a theme colour name such as raised, or a colour such as #8a9bb0 (usually the image's own average colour). The image then fades in from a blur, unless the device asks for reduced motion. | either |
lazy | Waits until the image is near the visible part of the screen before loading it. lazy={false} loads it at once. | either |
zoomable | Pinching, the mouse wheel and double-tapping zoom the image, and dragging pans it while zoomed. Swiping down while not zoomed runs on:dismiss. Written zoomable={condition}, the gestures come and go with the condition; zoomable={false} is not zoomable. | either |
<input>
A single-line text field. Always the platform's real text field.
Stability: experimental · Events: on:input, on:change, on:focus, on:blur, on:key · On the web: <input>
| Attribute | Means | Written as |
|---|---|---|
value | The current text. | either |
bind:value | Two-way binding to a state variable: the field shows the state, and typing writes the state. Written bind:value={name}, where name is a state variable of this page or component. | expression |
placeholder | Hint text shown while empty. | either |
type | One of text, email, password, number, phone, search. | either |
autocomplete | What the field holds, so the browser, iOS (textContentType) and Android (autofill hints) can offer saved values: a word from the HTML autocomplete list, such as email, username, current-password, new-password, one-time-code, name, tel or postal-code; off offers none (decision 0106). Android has no hint for nickname, organization, organization-title, cc-name or url, so the native build refuses them written as text (E0519). | either |
disabled | While true | either |
invalid | While true | either |
<textarea>
A text field of several lines. Always the platform's real text field.
Stability: experimental · Events: on:input, on:change, on:focus, on:blur · On the web: <textarea>
| Attribute | Means | Written as |
|---|---|---|
value | The current text. | either |
bind:value | Two-way binding to a state variable, as on input. | expression |
placeholder | Hint text shown while empty. | either |
rows | How many lines tall the field is before it scrolls. | either |
autocomplete | What the field holds, as on input, such as street-address. | either |
disabled | While true | either |
invalid | While true | either |
<list>
Repeats its children for each item of a state value. Recycles rows on native.
Stability: experimental · Requires each, as · On the web: <div>
| Attribute | Means | Written as |
|---|---|---|
each | The state value to repeat over. | expression |
as | The name each item is given inside the list. | text |
key | An expression giving each item a stable identity, such as key={post.id}. Rows with the same key are kept, with their focus and typed text, and only moved when the items are reordered. Without key, rows are matched by position. | expression |
index | The name the item's position (counted from 0) is given inside the list, such as index="i". | text |
<scroll>
A container that scrolls when its content overflows.
Stability: experimental · On the web: <div>
<form>
A container that groups fields and sends them together. Sending it runs on:submit and never reloads the page. The browser's own checks (such as on an email field) are off, so they never stop on:submit; check fields with the rules from @duolith/client.
Stability: experimental · Events: on:submit, on:key · On the web: <form>
<toggle>
An on/off switch. Always the platform's real switch.
Stability: experimental · Events: on:change, on:focus, on:blur · On the web: <input>
| Attribute | Means | Written as |
|---|---|---|
checked | Whether the switch is on. | either |
bind:checked | Two-way binding to a state variable holding true or false. Written bind:checked={name}, where name is a state variable of this page or component. | expression |
disabled | While true | either |
<checkbox>
A box that is ticked or not. Always the platform's real checkbox.
Stability: experimental · Events: on:change, on:focus, on:blur · On the web: <input>
| Attribute | Means | Written as |
|---|---|---|
checked | Whether the box is ticked. | either |
bind:checked | Two-way binding to a state variable holding true or false, as on toggle. | expression |
disabled | While true | either |
<slider>
Picks a number from a range by dragging, or with the arrow keys when focused. Always the platform's real slider.
Stability: experimental · Events: on:input, on:change, on:focus, on:blur · On the web: <input>
| Attribute | Means | Written as |
|---|---|---|
value | The current number. | either |
bind:value | Two-way binding to a state variable holding a number. | expression |
min | The smallest number | either |
max | The largest number | either |
step | The distance between neighbouring numbers | either |
disabled | While true | either |
<progress>
How far a task has got, as a bar. Without value it shows that work is going on, for an unknown time.
Stability: experimental · On the web: <progress>
| Attribute | Means | Written as |
|---|---|---|
value | How far the task has got, from 0 to 1. | either |
<icon>
A glyph from the built-in icon set, in the colour of the surrounding text and sized by its utilities (1.25em square unless they say otherwise). It is hidden from assistive technology unless it has a label.
Stability: experimental · Requires name · On the web: <span>
| Attribute | Means | Written as |
|---|---|---|
name | The icon's name, from spec/kit/icons.yaml, such as chevron-right. | either |
<overlay>
Content shown above the screen: a dialog, a sheet, a popover, a menu, a listbox, a tooltip or the toast region. Its kind decides how it is placed, whether it is modal and the keys it answers to. It is shown while open is true, in the screen's overlay layer above everything else, wherever it is written. Modal kinds keep focus inside, make the screen behind them unavailable and stop it scrolling; every kind returns focus to where it came from on close. An overlay written inside another one belongs to it: when that one closes, the inner one gets on:dismiss and is hidden, and it shows again only if it is still open when the outer one reopens.
Stability: experimental · Requires kind · Events: on:dismiss, on:detent · On the web: <div>
| Attribute | Means | Written as |
|---|---|---|
kind | One of the kinds listed under overlays below, such as dialog, sheet or menu. | text |
open | While true, the overlay is shown. Written open={...}; a tooltip and the toast region open by themselves. | either |
anchor | The id of the element the overlay belongs to, such as the button that opens it. That trigger is told whether the overlay is open, focus returns to it on close, and an anchored kind is placed next to it. | either |
placement | Where an anchored kind sits next to its anchor: one of the placements listed below. It flips to the other side, and shifts along, to stay on screen. | either |
detent | How tall a sheet opens: medium (about half the screen) or large. Dragging the sheet moves between them. | either |
Control flow
<show>
Shows its children while when is truthy. It may be followed directly by an otherwise element, whose children are shown while when is falsy.
Stability: experimental · Requires when
| Attribute | Means | Written as |
|---|---|---|
when | The condition, written in braces. | expression |
<otherwise>
The children shown while the show element directly before it is hidden. Only whitespace may sit between </show> and <otherwise>.
Stability: experimental
<match>
Shows the children of the one case whose is word equals value, such as <match value={feed.state.status}>. Its children are case elements only. Without a <case else>, every member of value's union needs a case, and a missing one fails the build (E0500), so a new state is never silently not shown (decision 0098). It works on a union of words only: a union of numbers or booleans gives E0500 and E0501, so use show there. A cast in value, such as value={tone as "info"}, is trusted, and passes the members it leaves out.
Stability: experimental · Requires value
| Attribute | Means | Written as |
|---|---|---|
value | The value to match, written in braces; usually a union of words, or a tagged union's tag such as result.status. | expression |
<case>
Directly inside a match, the children shown when the match's value is this case's is word. Inside it, the value (and the union it is the tag of) is narrowed to that member. <case else>, last, is shown for every value no other case names.
Stability: experimental
| Attribute | Means | Written as |
|---|---|---|
is | The value this case shows for, such as is="ready". | text |
else | Written alone | text |
<slot>
Inside a component, the place where the children passed to the component are shown. Written <slot />. With a name, such as <slot name="leading" />, it shows the piece of that name instead.
Stability: experimental
| Attribute | Means | Written as |
|---|---|---|
name | The piece to show here. Without it | text |
<piece>
Directly inside a placed component, children meant for one named place in it, such as <piece name="leading"><Avatar name="Ada" /></piece>. The component shows them where it writes <slot name="leading" />.
Stability: experimental · Requires name
| Attribute | Means | Written as |
|---|---|---|
name | The name of the component's slot that shows these children. | text |
<boundary>
A part of the screen that loads and fails on its own. While loading is true it shows a skeleton in the shape of its children; if its children throw while they are built or updated, it shows its fallback instead of breaking the screen (decisions 0058 and 0059).
Stability: experimental
| Attribute | Means | Written as |
|---|---|---|
loading | While true, the boundary shows its skeleton, such as loading={feed.loading}. The skeleton is derived from the children's layout, or is the shape they last had when remember is set. | expression |
remember | A name to remember the children's shape under, so the next skeleton has the shape the content last had, such as remember="feed". | text |
<fallback>
Directly inside a boundary, what it shows when its other children fail. With as, its expressions see the failure: failure.message says what went wrong and failure.retry() builds the children again. Without a fallback, a boundary shows a sentence and a Try again button.
Stability: experimental
| Attribute | Means | Written as |
|---|---|---|
as | The name the failure is given inside the fallback, such as as="failure". | text |
Attributes every element accepts
| Attribute | Means | Written as |
|---|---|---|
class | Utility classes from the theme, and classes defined in this page's style block. | text |
href | Makes the element navigate to a route when pressed, such as href="/post/7", without reloading the app. A link to another site, or pressed with a modifier key, opens as usual. Written as text for a fixed route or in braces for one built from state. | either |
current | Marks the element as the current item of a set of links, such as the active tab: current={route().path.startsWith("/feed")}. Assistive technology announces it, and a style block can select it with [aria-current] on the web. Written without a value, it always marks the element. Instead of true it may give the kind of item: page, step, location, date or time, such as current={isToday ? "date" : false} in a calendar. | expression |
label | The accessible name, where the content does not describe itself. | either |
id | A name for the element, unique on the screen, that described-by can point at. In a component, make it unique for each placed copy. | either |
described-by | The id of the element whose text describes this one, such as a field's hint or error. Assistive technology reads it after the element's name. | either |
labelled-by | The id of the element whose text names this one, used instead of label where that name is already on the screen, such as the tab that names a tab panel. | either |
role | What the element is to assistive technology, where its element does not say so already. One of the words listed under roles below, written as text so it can be checked. | text |
expanded | Whether what the element shows and hides, such as an accordion's section, is open: expanded={open}. Assistive technology announces expanded or collapsed (decision 0108). | expression |
sorted | For an element with role column-header: how its table's rows are sorted by that column, sorted={sort === "total" ? "descending" : "none"}. Assistive technology announces it (decision 0108). | either |
selected | Whether the element is the chosen one of its group, such as one radio of a radio-group, one tab of a tab-list or one day of a grid. Written selected={...}. | either |
tab-stop | Whether the element is its group's one Tab stop, written tab-stop={condition}: keyboard focus reaches the group through it, and its siblings are skipped by Tab. Written with no value, the element is always a Tab stop, which makes a view focusable. After an on:key handler runs, focus follows the Tab stop (decision 0037). | either |
controls | The id of the element this one shows or changes, such as the panel a tab shows. Assistive technology offers to jump there. | either |
value-now | For an element with role spinbutton: its current number, as assistive technology reads it. | either |
value-min | For an element with role spinbutton, the smallest number it takes. | either |
value-max | For an element with role spinbutton, the largest number it takes. | either |
value-text | For an element with role spinbutton: the value as words, read instead of value-now, such as "9 AM" or "3 guests". | either |
class:* | A class applied only while the condition holds, written class:name={condition}. The name is a utility, with any prefixes, or a class from this file's style block. It wins over the element's class attribute where the two disagree. | expression |
motion | How the element moves when a show or a list adds or removes it: one of the presets listed under motions below, such as motion="slide-up". On a list it is the preset of every row. Without it, elements a show or list adds or removes fade and settle, and rows that move glide to their new place; motion="none" turns that off. Reduced motion turns every preset into a short fade (decision 0055). | text |
morph | A name that carries the element from one screen to the next: when the screen being left and the screen arriving each have an element with the same morph, such as morph={post-${post.id}} on a thumbnail and on the post's picture, it travels from its old place and size to its new one during the transition (decision 0056). | either |
Events
| Event | Runs | The handler receives |
|---|---|---|
on:press | Runs when the element is pressed (tap, click, or Enter and Space when focused). | {} |
on:input | Runs as the user types. The handler receives an object with the field's current value. | { readonly value: string } |
on:change | Runs when the user commits a change: leaving a text field after editing it, or flipping a toggle. The handler receives an object with the current value, or with checked for a toggle. | { readonly value?: string; readonly checked?: boolean } |
on:submit | Runs when a form is sent, by pressing a button marked submit or Enter in one of its fields. The page never reloads; the handler receives an empty object. | {} |
on:focus | Runs when the element receives keyboard focus. | {} |
on:blur | Runs when the element loses keyboard focus. | {} |
on:longpress | Runs when the element is held for 500 ms without moving. The release that ends a long press is not also a press. | {} |
on:swipe | Runs when a finger, or a pointer held down, moves quickly across the element, at least 40 px mostly in one direction, and lifts. The handler receives the direction: left, right, up or down. A swipe down counts only while what scrolls around the element is at its top, so pulling down to refresh and scrolling back up are never both. A swipe is not also a press. Every swipe needs another way to do the same, such as a button, for keyboards and assistive technology (decision 0121). | { readonly direction: "left" | "right" | "up" | "down" } |
on:key | Runs when a navigation key is pressed while focus is on the element or inside it: an arrow key, Home, End, PageUp, PageDown or Escape. The handler receives the key's name, such as ArrowDown, and the key does nothing else (the page does not scroll). Inside a text field only Escape arrives, so the arrows still move the caret; in a field with role combobox, ArrowDown and ArrowUp arrive too, to open its suggestions. A phone's field hears no keys, so what a field's keys do must also be reachable by touch. Afterwards focus moves to the element's Tab stop (tab-stop) if it has moved (decision 0037). | { readonly key: string } |
on:load | Runs when an image has loaded and is shown. | {} |
on:error | Runs when an image cannot be loaded, so the page can show something else. | {} |
on:dismiss | Runs when the person asks to close something: on an overlay, Escape, a press on the backdrop or outside an anchored overlay, or a sheet dragged down, and the overlay stays open until the handler sets its open to false; on a zoomable image that is not zoomed in, a swipe down, the gesture that closes a full-screen viewer. | {} |
on:detent | Runs on a sheet when it is dragged to another detent. The handler receives an object with the detent it was dragged to, medium or large, as its value. | { readonly value?: string } |
Roles
| role= | On the web |
|---|---|
group | group |
radio-group | radiogroup |
radio | radio |
status | status |
alert | alert |
heading | heading |
image | img |
separator | separator |
alert-dialog | alertdialog |
menu-item | menuitem |
option | option |
combobox | combobox |
search | search |
grid | grid |
table | table |
row | row |
gridcell | gridcell |
cell | cell |
column-header | columnheader |
tab-list | tablist |
tab | tab |
tab-panel | tabpanel |
spinbutton | spinbutton |
dialog | dialog |
navigation | navigation |
banner | banner |
toolbar | toolbar |
Overlay kinds
| kind= | What it is | Role |
|---|---|---|
dialog | A modal in the middle of the screen, over a backdrop. | dialog |
sheet | A modal panel from the bottom edge (from the side on a wide window), with medium and large detents, dismissed by dragging it down or pressing the backdrop. | dialog |
popover | Non-modal content next to its anchor. A press outside it dismisses it. | dialog |
menu | Actions next to its anchor. The arrow keys, Home, End and typing a letter move between its menu-item elements; Tab closes it. | menu |
listbox | Options next to its anchor, as a select shows them, with the same keys as a menu between its option elements. | listbox |
tooltip | A short description of its anchor, shown on hover and focus after a delay and hidden by Escape. The anchor is described by it. | tooltip |
toasts | The toast region: a polite live region at the screen's edge, above modals. Its toasts pause while it is hovered or focused, and can be swiped away. | region |