Duolith docs

The kit: built-in parts

The kit is a set of ready-made parts (buttons, rows, fields, switches, empty and error states) that look right in any theme, in light and dark, and are accessible from the start. Import the ones a page uses:

import { Button, ListRow, Section, TextField } from "@duolith/kit";

Then place them like any component:

<Section title="Account">
  <ListRow title="Email" value="ada@example.com" icon="mail" chevron href="/email" />
</Section>
<TextField label="Name" bind:value={name} error={nameError} />
<Button label="Save" icon="check" loading={saving} onPress={save} />

The runnable gallery, with every part, variant, size and state, is examples/kit, and for the pickers, filters, tabs and media, examples/inputs-and-media:

duolith dev examples/kit --port 4400
duolith dev examples/inputs-and-media --port 4401

Parts are .duo components (in packages/kit/parts/) built into the duolith command, so there is nothing to install, and a build includes only the parts a project imports. Each part's full specification (props, pieces, states, accessibility, tokens) is in spec/kit/<part>.yaml. Decisions: 0028 (the kit), 0029 (the language features below), 0030 (icons), 0034 to 0036 (overlays and toasts), 0037 (keys and Tab stops), 0038 (the image cache), 0039 (chips and zoom), 0040 and 0041 (the navigation parts), 0042 (the public folder).

The parts

FamilyPartWhat it is
ButtonsButtonlabel, variant (primary, secondary, ghost, danger), size (sm, md, lg), icon, iconEnd, loading, disabled, full, submit, onPress
IconButtonicon and label (required: it is the accessible name), variant, size, selected for a button that stays on, disabled, onPress
Lists and cardsListRowtitle, subtitle, value, icon, chevron, destructive, disabled; a button with onPress, a link with href; pieces leading and trailing
Sectionrows on one surface with lines between them; title, footer, action with onAction
Cardtitle, subtitle, flat, onPress (the whole card is one button); piece media
Avatarname (initials and accessible name), src, size (sm, md, lg, xl), status (online, away, offline)
Badgelabel, tone (neutral, primary, success, danger), solid, icon
Dividera line; label, inset, vertical
InputsTextFieldlabel, bind:value, placeholder, hint, error, type, icon, disabled, onChange
TextArealabel, bind:value, placeholder, hint, error, rows, limit (shows a count), disabled
SelectionToggleRowlabel, hint, icon, bind:checked, disabled, onChange
Checkboxlabel, hint, bind:checked, disabled; pressing the label ticks it
RadioGrouplabel, options ({ value, label, hint? }[]), bind:value, disabled
SegmentedControllabel, options ({ value, label, icon? }[]), bind:value, disabled
Sliderlabel, bind:value (a number), min, max, step, unit, disabled
Chiplabel, bind:selected, icon, disabled, onPress (decides instead of flipping)
ChipGrouplabel, options ({ value, label, icon? }[]), bind:value (the chosen value), multiple with bind:values (the chosen list), disabled
PickersDatePickeran inline month: label, bind:value (ISO date such as "2026-11-14"), min, max, disabledDates (a list or a function), locale, disabled
TimePickerlabel, bind:value ("HH:MM", 24-hour), step (minutes), locale (12 or 24 hours and AM/PM words), disabled
Steppera number with − and +: label, bind:value, min, max, step, unit, disabled
Search and tabsSearchFieldlabel, bind:value, placeholder, disabled, onSubmit; a clear button, Escape empties it
Tabsin-page tabs (not the app's tab bar): label, tabs ({ value, label, icon?, disabled? }[]), bind:selected; children are the panel
MediaImagesrc, alt or decorative, ratio (1:1, 4:3, 3:2, 16:9, 3:4, 2:3), fit (cover, contain), placeholder, radius, lazy, zoomable; piece fallback
ImageViewerfull screen and zoomable: src, alt, bind:open
FeedbackSkeletona loading placeholder: shape (line, circle, block), lines, width, size, label
Spinnersize, label; takes the text colour around it
ProgressBarvalue from 0 to 1 (none while unknown), label, showValue, tone
EmptyStatetitle, message, icon, action with onAction
ErrorStatetitle, message, icon, retry label, retrying, onRetry
NavigationTabBarthe bar of tabs at the bottom of a layout; label, rail (a column at the leading edge in a large window)
TabBarItemlabel, icon, href, badge (a count, shown above 0), exact, current (overrides the matching); current while the route is at href or below it
NavHeaderthe bar at the top of a screen: title, large, showBack, onBack, up and upTitle; a back button when the screen was pushed, an up button when there is nothing to go back to; pieces leading and trailing
Toolbara row of actions with one Tab stop; label, flat
Breadcrumbsitems ({ label, href? }[]), the last the current page; label
Linka text link; href, external, muted; marks http and https links to other sites
OverlaysSheettitle, bind:open, bind:detent (medium, large); piece trigger; children scroll. Drag the handle between detents or down to dismiss; from the side on a wide window
Dialogtitle, message, bind:open, dismissible; pieces trigger and actions; children are the body
AlertDialogtitle, message, confirmLabel, cancelLabel, destructive, bind:open, onConfirm, onCancel; piece trigger
Menulabel, items ({ label, icon?, destructive?, disabled?, onSelect? } or { divider: true }), bind:open, placement; piece trigger
Popoverlabel, bind:open, placement; piece trigger; children are its content
Tooltiptext, placement (top, bottom, left, right); wraps the control it describes
Toastthe toast region, placed once: position (bottom, top), label. Show toasts with toast() from @duolith/client
Selectlabel, options ({ value, label }[]), bind:value, placeholder, disabled
ActionSheettitle, actions ({ id, label, destructive? }[]), bind:open, cancel, onChoose; piece trigger
MoreAccordionsections ({ id, title, body }[]), bind:open (the open ids), multiple; each heading says expanded or collapsed
Bannertitle, message, tone (info, success, danger: an alert), action with onAction, onDismiss
Pagerone page at a time: label, pages ({ title, body?, image? }[]), bind:page; previous, next, a dot per page, and a swipe left or right
Paginationpages, bind:page (from 1), label; the pages near the current one, marked current
Ratinglabel, bind:value, max, readonly; a radio group of stars
ProgressRingvalue from 0 to 1, label, size (sm, md, lg)
Comboboxlabel, options, bind:value, placeholder, onChoose; suggests what matches as the user types, in a listbox the arrow keys reach
ChipInputlabel, bind:values, placeholder; Enter adds a chip, each chip has a remove button
DataTablelabel, columns ({ key, label, sortable?, numeric? }[]), rows, bind:sort, bind:descending; a table whose headers say how it is sorted
FileInputlabel, bind:files ({ name, size? }[]), icon, onPick (call the media-picker effect there)
Fabthe floating action button: label, icon, extended, onPress
GesturesSwipeRowlabel, actions ({ id, label, destructive? }[]), bind:open, onAction; a swipe left shows the actions, and its More button does too
PullToRefreshonRefresh (may return a promise), bind:refreshing, label; a pull down from the top, or its Refresh button, refreshes
Drawertitle, bind:open; piece trigger; a modal panel from the start edge, closed by Escape, the scrim, Close or a swipe left
DateRangePickerlabel, bind:start, bind:end, min, max, disabledDates, locale, disabled; DatePicker's grid choosing a start, then an end

The gesture parts hear on:swipe (decision 0121), which you can put on any <view>: on:swipe={(event) => ...} receives event.direction, one of left, right, up and down. A swipe down counts only from the top of what scrolls around the view. Give every swipe another way to do the same thing, such as a button, because a keyboard and a screen reader cannot swipe.

A misspelt import is caught at build time: import { Buton } from "@duolith/kit" is E0123, "Did you mean Button?". Import parts by name: import kit from "@duolith/kit" and import * as kit from "@duolith/kit" are E0129.

Binding a part to state

Fields, switches and pickers bind both ways, like the elements inside them:

---
import { state } from "@duolith/client";
import { RadioGroup, Slider, TextField, ToggleRow } from "@duolith/kit";

let email = state("");
let notifications = state(true);
let plan = state("monthly");
let volume = state(40);
const plans = [
  { value: "monthly", label: "Monthly", hint: "£4 a month" },
  { value: "yearly", label: "Yearly", hint: "£40 a year" },
];
---
<TextField label="Email" type="email" bind:value={email} />
<ToggleRow label="Notifications" bind:checked={notifications} />
<RadioGroup label="Plan" options={plans} bind:value={plan} />
<Slider label="Volume" unit="%" bind:value={volume} />

Leave the binding out and the part keeps its own value, starting from value="..." if you pass one.

Your own components can do the same: declare the prop with a bindable(...) default, and bind it inside.

components/Search.duo
---
import { bindable, props } from "@duolith/client";
let { query = bindable("") } = props<{ query?: string }>();
---
<input type="search" bind:value={query} />

Only bindable props can be bound (E0108) or assigned by the component (E0114). Passed one way instead (<TextField value={name} />), the part keeps what is typed as its own until name changes, and then shows the new value.

Leading and trailing content: pieces

ListRow shows children at its trailing edge. To put something before the title, or to be explicit, give it in a piece:

<ListRow title="Ada Lovelace" subtitle="Online now" onPress={openChat}>
  <piece name="leading"><Avatar name="Ada Lovelace" status="online" /></piece>
  <piece name="trailing"><Badge label="New" tone="primary" /></piece>
</ListRow>

Card has a media piece for full-bleed content above its title. A component of your own offers a piece by writing <slot name="leading" />. A piece the component does not show is E0127; the same piece given twice is E0128; <piece> anywhere but directly inside a placed component is E0126.

Overlays: sheets, dialogs, menus, popovers, tooltips, toasts and select

Overlay parts show above the screen. Open one from state with bind:open, or give it the control that opens it in a trigger piece; that control is told whether the overlay is open, and focus goes back to it when the overlay closes.

---
import { state, toast } from "@duolith/client";
import { AlertDialog, Button, Dialog, IconButton, Menu, Select, Sheet, TextField, Toast, Tooltip } from "@duolith/kit";

let editing = state(false);
let confirming = state(false);
let name = state("Ada");
let country = state("gb");
const countries = [{ value: "fr", label: "France" }, { value: "gb", label: "United Kingdom" }];
const actions = [
  { label: "Edit", icon: "edit", onSelect: () => (editing = true) },
  { divider: true },
  { label: "Delete", icon: "trash", destructive: true, onSelect: () => (confirming = true) },
];
---
<Menu label="Post actions" items={actions}>
  <piece name="trigger"><IconButton icon="more" label="More" /></piece>
</Menu>
<Dialog title="Edit name" bind:open={editing}>
  <TextField label="Name" bind:value={name} />
  <piece name="actions"><Button label="Save" onPress={() => { editing = false; toast("Saved"); }} /></piece>
</Dialog>
<AlertDialog title="Delete this post?" confirmLabel="Delete" destructive bind:open={confirming}
  onConfirm={() => toast("Deleted", { action: { label: "Undo", onPress: undo } })} />
<Sheet title="Share"><piece name="trigger"><Button label="Share" /></piece>...</Sheet>
<Tooltip text="Add to favourites"><IconButton icon="star" label="Favourite" /></Tooltip>
<Select label="Country" options={countries} bind:value={country} />
<Toast />

toast(message, { tone, action, duration }) comes from @duolith/client and can be called from any script; place <Toast /> once on the page to show them (decision 0036). Tones are neutral, success and danger; a toast goes after 5 seconds (8 with an action), at most three show at once and the rest wait, and they pause while the pointer or focus is on them. Swipe one sideways to dismiss it.

The runnable gallery, every overlay open in each state, light and dark, is examples/overlays.

PartWhat assistive technology hearsKeyboard and focus
Sheet, Dialoga modal dialog named by its titlefocus moves to its first control; Tab stays inside; the page behind is inert and does not scroll; Escape (and the backdrop) close it; focus returns to the trigger
AlertDialogan alertdialog, described by its messagefocus starts on Cancel, the safe choice; Escape cancels; the backdrop does nothing
Menua menu of menu items; its trigger has aria-haspopup="menu" and aria-expandedArrowDown/ArrowUp (wrapping), Home, End, a letter jumps to the next item starting with it; Enter chooses; Escape or Tab closes; ArrowDown on the trigger opens it
Popovera dialog that is not modalfocus moves in; a press outside or Escape closes it
Tooltipthe control is described by the tooltip's textshows 500 ms after hover or focus; Escape hides it
Toasta polite live region; error toasts are alertsnever takes focus; its buttons are reachable with Tab
Selecta combobox that opens a listbox; each option selected or notEnter, Space or ArrowDown opens it on the chosen option; arrows, Home, End and letters move; Enter chooses; Escape closes without choosing

These parts are built on one element, <overlay kind="...">, which your own components can use too (decision 0034): kind is dialog, sheet, popover, menu, listbox, tooltip or toasts; open={...} shows it; anchor={id} names the element it belongs to (needed by the anchored kinds, E0151) and placement (top, bottom, with -start or -end, or left, right) where it sits, flipping and shifting to stay on screen; on:dismiss runs when the person asks to close it, and the overlay closes when you set open to false; on:detent runs when a sheet is dragged to another detent. An unknown or empty kind is E0150, a missing or empty anchor E0151, a placement E0152, a detent E0153, and an attribute written twice E0154.

Variants and conditional classes

A part's variants are props, and the part turns them into classes with class:name={condition}, which you can use in your own files too:

<button
  class="row items-center gap-2 p-3 rounded-md"
  class:bg-primary={variant === "primary"}
  class:text-on-primary={variant === "primary"}
  class:chosen={isChosen}
>

The name is one utility (prefixes allowed, such as class:pressed:opacity-75) or a class from the file's style block. It applies while the condition holds, and wins over the element's class where the two disagree.

The navigation parts sit on the router (see navigation): tabs are links, and the header's back button calls back(). The runnable example is examples/navigation-kit, a small app with every part, light and dark, with the tab bar as a rail on a wide window.

A tab bar goes in a layout, so it stays while the screens inside it change:

pages/_layout.duo
---
import { state } from "@duolith/client";
import { TabBar, TabBarItem } from "@duolith/kit";

let unread = state([1, 2, 3], { shared: "unread" });
---
<view class="lg:row">
  <slot />
  <TabBar rail>
    <TabBarItem label="Home" icon="home" href="/" />
    <TabBarItem label="Inbox" icon="inbox" href="/inbox" badge={unread.length} />
    <TabBarItem label="Settings" icon="settings" href="/settings" />
  </TabBar>
</view>

Each item is current while the route is at its href (without its query, fragment or trailing slash) or below it (/inbox/7 keeps Inbox current); exact limits that to href itself, and / is always matched exactly. A tab that owns routes elsewhere says so with current={route().path.startsWith("/post/")}. rail turns the bar into a column at the leading edge from 1024px wide; the view around it must then be lg:row, as above. The bar keeps clear of the home indicator (env(safe-area-inset-bottom)).

Each screen starts with its header:

<screen title="Message">
  <NavHeader title="Message">
    <piece name="trailing"><IconButton icon="trash" label="Delete" onPress={remove} /></piece>
  </NavHeader>
  ...
</screen>

The back button appears by itself when the screen was pushed from another one, showing that screen's title ("‹ Inbox", named "Back to Inbox"). The first screen of a visit, a screen opened from its address and a screen a tab opened have none. Your own markup can ask the same thing with canGoBack() and backTitle() from @duolith/client. A screen opened from its address has nothing to go back to; give it up="/inbox" upTitle="Inbox" and it shows "‹ Inbox" there instead, replacing the screen with its parent. large puts a big title under the bar, which scrolls away under it while the bar's title fades in; showBack={false} never shows the button, and onBack runs instead of back().

<Toolbar label="Message actions">
  <IconButton icon="send" label="Reply" onPress={reply} />
  <IconButton icon="star" label="Star" selected={starred} onPress={toggleStar} />
</Toolbar>

<view class="hidden lg:flex">
  <Breadcrumbs items={[{ label: "Library", href: "/library" }, { label: "Travel" }]} />
</view>

<Link href="/settings">Settings</Link>
<Link href="https://example.com/terms">Terms</Link>

Theming

Parts use only theme tokens: colours such as primary, surface, raised, ink, muted, danger and success, the radius and space scales, and the text styles. Change them in your project's theme.yaml and every part follows, in light and dark (see styling). A part never uses a literal colour; pnpm check enforces it.

Each part also reads tokens of its own, var(--part-<part>-<token>), declared under look: in its spec with a value for each platform look where they differ. A theme changes them under parts:, and look: platform picks the iOS or Material values (see styling). A test checks that every token a part reads is declared, and every declared one is read.

TextField passes autocomplete to its field, so <TextField label="Password" type="password" autocomplete="current-password" /> lets the browser, iOS and Android offer the saved password. Android has no autofill hint for nickname, organization, organization-title, cc-name or url, so a native build refuses them (E0519); the web build takes them.

Accessibility

PartWhat assistive technology hearsKeyboard
Button, IconButtona button named by its label; selected makes IconButton a toggle (pressed or not)Tab to reach, Enter or Space to press; disabled ones are skipped
ListRowa button with onPress, a link with href, otherwise plain text; a disabled row is never a link and is marked disabledthe same; disabled rows are skipped
TextField, TextAreaa text field named by its label and described by its error, or else its hint; error marks it invalid and announces the messageTab
ToggleRow, Checkboxa switch or a checkbox named by its label and described by its hintSpace flips it
RadioGroup, SegmentedControla radio group named by its label, each option a radio, checked or notone Tab stop, on the chosen option (or the first); arrow keys move and choose, wrapping at the ends
Slidera slider named by its labelarrow keys, Home, End
Spinner, ProgressBara status, a progress barnone
ErrorStatean alert, announced when it appearsTab to the retry button
Chip, ChipGrouptoggle buttons (pressed or not) in a group named by its labeleach chip a Tab stop; Enter or Space flips it
DatePicker, DateRangePickera grid named by the label and month; each day a gridcell named by its full date, the chosen one selected (DateRangePicker: the start, the end and the days between, named "…, start", "…, end" or "…, in range", with a status reading the range)one Tab stop, on the focused day; arrows move a day or a week, Home and End to the week's ends, PageUp and PageDown a month, skipping days that cannot be chosen; Enter or Space chooses
TimePicker, Stepperspinbuttons with their value, minimum, maximum and value text; AM and PM a radio grouparrows step, PageUp and PageDown step further, Home and End to the ends; the − and + buttons are not Tab stops
SearchFielda search landmark holding a search boxEnter submits, Escape empties
Tabsa tab list of tabs (selected or not, each controlling the panel) over a tab panelone Tab stop on the chosen tab; arrows show the next or previous tab, wrapping and skipping disabled ones; Home, End
Skeletonnothing, or with label a status that announces itnone
Image, ImageVieweran image named by alt (decorative ones are skipped); the viewer a dialoga zoomable Image is a button; the viewer takes focus, keeps Tab inside, closes with Escape and gives focus back
TabBar, TabBarItema navigation landmark named Tabs; each tab a link, the current one aria-current="page", named "Inbox, 3 new" with a badgeTab to each tab, Enter follows
NavHeadera banner holding the title as a heading; the back button named Back or "Back to Settings"Tab to the back button and the actions
Toolbara toolbar named by its labelone Tab stop (the control used last, or the first); arrow keys move without pressing, wrapping, Home and End go to the ends, disabled controls are skipped; keys with a modifier and caret keys in a text field are left alone
Breadcrumbsa navigation landmark named Breadcrumb; the last item aria-current="page" and not a link; a crumb for the screen before goes back to itTab to each link
Linka link; an http or https one to another site adds "opens another site"Tab, Enter
Comboboxa combobox (the field) controlling a listbox of options, aria-expanded while it showstyping keeps focus in the field; ArrowDown and ArrowUp move into the options, Enter chooses and returns to the field, Escape closes and stays in it
DataTablea table of rows, column headers and cells; each sortable header has aria-sort, its button named "Sort by Name"Tab to each sort button, Enter or Space sorts, then reverses
SwipeRowa group named by its label; the More button says whether the actions are expanded; each action a buttonTab to More, Enter shows the actions, each then a Tab stop
PullToRefresha Refresh button, and a status that says RefreshingTab to Refresh, Enter refreshes
Drawera modal dialog named by its titlefocus moves in and stays; Escape closes it and gives focus back to the trigger

Every focusable part shows a 2px outline in the primary colour when reached by keyboard.

These come from three small language features you can use anywhere: role (one of group, radio-group, radio, status, alert, heading, image, separator, navigation, banner, toolbar, alert-dialog, menu-item, option, combobox, table, cell, and the words under "Keys and Tab stops" below; E0124 otherwise), selected={...}, sorted (ascending, descending or none, on a column header), invalid and described-by={id} (with id), plus label and disabled. A view with role="radio-group" gets the one Tab stop and arrow keys by itself, and so does a view with role="toolbar" (moving focus without choosing).

Keys and Tab stops in your own files

The pickers and tabs are built from two small features you can use too (decision 0037). on:key={(event) => ...} hears the navigation keys (arrows, Home, End, PageUp, PageDown, Escape) on an element or inside it, and the key does nothing else. tab-stop={condition} makes an element its group's one Tab stop, or with no value makes a view focusable. After an on:key handler, focus moves to the element's Tab stop, so you move focus by changing state:

<view role="tab-list" label="Sections" on:key={(event) => move(event.key)}>
  <list each={tabs} as="tab" key={tab.value}>
    <button role="tab" selected={tab.value === chosen} tab-stop={tab.value === chosen}>{tab.label}</button>
  </list>
</view>

A spinbutton takes value-now, value-min, value-max and value-text; a tab points at its panel with controls={id}. The role words grew: search, grid, row, gridcell, column-header, tab-list, tab, tab-panel, spinbutton, dialog.

Images

An <image> (and the Image part) needs alt, saying what it shows, or decorative when it adds nothing for a screen reader user (E0160). Every address is fetched and decoded once for the whole app, however many images show it (decision 0038): the first one shows its placeholder colour and fades in from a blur, and later ones, on any screen, appear at once. lazy waits until the image is near the screen; on:load and on:error say how it went, which is how Image shows its fallback piece:

<Image src="/photos/lake.svg" alt="A lake below mountains" ratio="16:9" placeholder="#7fa7bd" zoomable>
  <piece name="fallback"><icon name="image" /></piece>
</Image>

zoomable on an image gives it pinch, wheel and double-tap zoom and panning; <Image zoomable> opens it full screen in an ImageViewer (decision 0039). On a plain <image>, decorative={...} and zoomable={...} follow their condition, and zoomable={false} is not zoomable. placeholder is one of the theme's colour names, such as raised, or any CSS colour.

Put an app's own images in public/ (public/photos/lake.jpg is /photos/lake.jpg): any file is copied as it is, PNG and JPEG as well as SVG, leaving out names that start with a dot and symbolic links. A public file cannot take a path the build writes, such as index.html or anything under _duolith/ (E0161, decision 0042). Files in public/ are served from the app's own origin, so an SVG opened directly can run script as the app: only put SVG files there that you trust like your own code.

Icons

<icon name="chevron-right" /> draws an icon from the built-in set in spec/kit/icons.yaml, in the colour of the text around it, 1.25em square unless utilities size it (w-6 h-6). It is hidden from screen readers unless you give it a label. Parts take icon names as props, such as <Button icon="plus" />. A name written as text is checked at build time (E0125, with a suggestion).

alert, arrow-left, arrow-right, arrow-up-right, bell, bookmark, calendar, camera, check, check-circle, chevron-down, chevron-left, chevron-right, chevron-up, clock, close, copy, download, edit, eye, filter, globe, heart, home, image, inbox, info, link, location, lock, mail, menu, minus, moon, more, phone, plus, refresh, search, send, settings, share, star, sun, trash, upload, user, users, wifi, wifi-off.

New elements

The kit is built from the language's own elements, and needed four new ones, which pages can use directly: textarea (several lines, bind:value, rows), checkbox (bind:checked), slider (min, max, step, bind:value gives a number) and progress (value from 0 to 1, or none while unknown). Each is the platform's real control.