Duolith docs

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>

AttributeMeansWritten as
titleThe title shown in the navigation header and the browser tab, as text or as an expression that the title follows.either
descriptionWhat 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>

AttributeMeansWritten as
disabledWhile 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>

AttributeMeansWritten as
levelWith 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>

AttributeMeansWritten as
submitMakes pressing the button send the form it is in.none
disabledWhile 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>

AttributeMeansWritten as
srcThe image address.either
altWhat the image shows, for screen readers. Required unless decorative.either
decorativeThe 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
placeholderThe 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
lazyWaits until the image is near the visible part of the screen before loading it. lazy={false} loads it at once.either
zoomablePinching, 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>

AttributeMeansWritten as
valueThe current text.either
bind:valueTwo-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
placeholderHint text shown while empty.either
typeOne of text, email, password, number, phone, search.either
autocompleteWhat 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
disabledWhile trueeither
invalidWhile trueeither

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

AttributeMeansWritten as
valueThe current text.either
bind:valueTwo-way binding to a state variable, as on input.expression
placeholderHint text shown while empty.either
rowsHow many lines tall the field is before it scrolls.either
autocompleteWhat the field holds, as on input, such as street-address.either
disabledWhile trueeither
invalidWhile trueeither

<list>

Repeats its children for each item of a state value. Recycles rows on native.

Stability: experimental · Requires each, as · On the web: <div>

AttributeMeansWritten as
eachThe state value to repeat over.expression
asThe name each item is given inside the list.text
keyAn 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
indexThe 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>

AttributeMeansWritten as
checkedWhether the switch is on.either
bind:checkedTwo-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
disabledWhile trueeither

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

AttributeMeansWritten as
checkedWhether the box is ticked.either
bind:checkedTwo-way binding to a state variable holding true or false, as on toggle.expression
disabledWhile trueeither

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

AttributeMeansWritten as
valueThe current number.either
bind:valueTwo-way binding to a state variable holding a number.expression
minThe smallest numbereither
maxThe largest numbereither
stepThe distance between neighbouring numberseither
disabledWhile trueeither

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

AttributeMeansWritten as
valueHow 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>

AttributeMeansWritten as
nameThe 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>

AttributeMeansWritten as
kindOne of the kinds listed under overlays below, such as dialog, sheet or menu.text
openWhile true, the overlay is shown. Written open={...}; a tooltip and the toast region open by themselves.either
anchorThe 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
placementWhere 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
detentHow 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

AttributeMeansWritten as
whenThe 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

AttributeMeansWritten as
valueThe 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

AttributeMeansWritten as
isThe value this case shows for, such as is="ready".text
elseWritten alonetext

<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

AttributeMeansWritten as
nameThe piece to show here. Without ittext

<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

AttributeMeansWritten as
nameThe 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

AttributeMeansWritten as
loadingWhile 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
rememberA 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

AttributeMeansWritten as
asThe name the failure is given inside the fallback, such as as="failure".text

Attributes every element accepts

AttributeMeansWritten as
classUtility classes from the theme, and classes defined in this page's style block.text
hrefMakes 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
currentMarks 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
labelThe accessible name, where the content does not describe itself.either
idA 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-byThe 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-byThe 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
roleWhat 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
expandedWhether 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
sortedFor 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
selectedWhether 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-stopWhether 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
controlsThe id of the element this one shows or changes, such as the panel a tab shows. Assistive technology offers to jump there.either
value-nowFor an element with role spinbutton: its current number, as assistive technology reads it.either
value-minFor an element with role spinbutton, the smallest number it takes.either
value-maxFor an element with role spinbutton, the largest number it takes.either
value-textFor 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
motionHow 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
morphA 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

EventRunsThe handler receives
on:pressRuns when the element is pressed (tap, click, or Enter and Space when focused).{}
on:inputRuns as the user types. The handler receives an object with the field's current value.{ readonly value: string }
on:changeRuns 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:submitRuns 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:focusRuns when the element receives keyboard focus.{}
on:blurRuns when the element loses keyboard focus.{}
on:longpressRuns when the element is held for 500 ms without moving. The release that ends a long press is not also a press.{}
on:swipeRuns 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:keyRuns 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:loadRuns when an image has loaded and is shown.{}
on:errorRuns when an image cannot be loaded, so the page can show something else.{}
on:dismissRuns 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:detentRuns 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
groupgroup
radio-groupradiogroup
radioradio
statusstatus
alertalert
headingheading
imageimg
separatorseparator
alert-dialogalertdialog
menu-itemmenuitem
optionoption
comboboxcombobox
searchsearch
gridgrid
tabletable
rowrow
gridcellgridcell
cellcell
column-headercolumnheader
tab-listtablist
tabtab
tab-paneltabpanel
spinbuttonspinbutton
dialogdialog
navigationnavigation
bannerbanner
toolbartoolbar

Overlay kinds

kind=What it isRole
dialogA modal in the middle of the screen, over a backdrop.dialog
sheetA 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
popoverNon-modal content next to its anchor. A press outside it dismisses it.dialog
menuActions next to its anchor. The arrow keys, Home, End and typing a letter move between its menu-item elements; Tab closes it.menu
listboxOptions next to its anchor, as a select shows them, with the same keys as a menu between its option elements.listbox
tooltipA short description of its anchor, shown on hover and focus after a delay and hidden by Escape. The anchor is described by it.tooltip
toastsThe 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