Reference

<xo-view>

@xoong/data import '@xoong/data/view';

Declare a screen: get names the GET operation to read. Children are bound to the result. Add live to apply server-sent updates.

Attributes

Events

• xo-done An action succeeded.
• xo-error A load or an action failed.
• xo-invalid A form was not sent because it is invalid.
• xo-notice A message for the toast.
• xo-go An action asked to go to another page.

Example

<xo-view get="listPeople" url-params="name,role">
  <p xo-if="$loading">Loading…</p>
  <p xo-if="$error">{$error.detail}</p>
  <ul>
    <li xo-each="items">{name} · {email}</li>
  </ul>
</xo-view>

Guide Data and tables

<xo-table>

@xoong/ui import '@xoong/ui';

A table for the list in the enclosing <xo-view get>. Children become the actions cell of each row.

Attributes

Events

• xo-columns-change The person showed or hid a column of the table.

Example

<xo-view get="listPeople">
  <xo-table columns="name,email:E-mail,role" sortable filters="name:Search by name" selectable page-size="10" empty="Nobody here">
    <span slot="role" class="badge">{role}</span>
    <button xo-click="deletePerson" xo-confirm="Delete {name}?" xo-notice="Deleted">Delete</button>
    <button slot="bulk" xo-click="deletePerson" xo-selected>Delete ticked</button>
  </xo-table>
</xo-view>

Guide Data and tables

<xo-form>

@xoong/ui import '@xoong/ui';

A form generated from the request schema of an operation.

Attributes

Events

• xo-done An action succeeded.
• xo-error A load or an action failed.
• xo-invalid A form was not sent because it is invalid.
• xo-dirty A form gained or lost unsaved changes.
• xo-reveal The form is about to focus an invalid field.
• xo-form-ready The form model exists.

Example

<xo-form op="createPerson" submit="Add person" xo-notice="Person added"></xo-form>

Guide Forms

<xo-dialog>

@xoong/ui import '@xoong/ui';

A modal on the native <dialog>. Open it with xo-open, close it with xo-close or by submitting a form inside. With heading it is a titled modal: a header with the title and a Close button, the content as the body, and the elements marked slot="footer" as the footer.

Attributes

Example

<button xo-open="#add">Add person</button>
<xo-dialog id="add" heading="Add person" size="wide" dismiss>
  <xo-form op="createPerson" submit="Add"></xo-form>
  <button slot="footer" xo-close>Cancel</button>
</xo-dialog>

Guide Dialogs and modals

<xo-toast>

@xoong/ui import '@xoong/ui';

Shows the message of the latest xo-error event on the page (not when the event was prevented with preventDefault(), or its handled is true because a view shows $error itself); hides on the next xo-done or after timeout seconds. Set detail.action ({ label, run }, for example Retry) and detail.timeout on the error and the toast shows that button, the same way an xo-notice does.

Attributes

Example

<xo-toast timeout="8"></xo-toast>

Guide Dialogs and modals

<xo-router>

@xoong/ui import '@xoong/ui';

A History-API router declared in markup: one <template xo-route> per route, optional <template xo-layout> shells. Links are intercepted, aria-current marks the active one. Guards and leave-vetoes are JavaScript (router.guard, router.beforeNavigate).

Attributes

Events

• xo-navigate The router moved to another location.
• xo-error A load or an action failed.

Example

<xo-router base="/admin" base-links>
  <template xo-layout="shell">
    <nav><a href="/users">Users</a></nav>
    <main xo-outlet></main>
  </template>
  <template xo-route="/users/:id" layout="shell" title="User">
    <xo-view get="getPerson" p-id=":id"><h1>{name}</h1></xo-view>
  </template>
  <template xo-route="*">Not found</template>
</xo-router>

Guide Router and page lifecycle

<xo-pager>

@xoong/ui import '@xoong/ui';

Previous and Next (and the "1–12 of 48" text) for any list in the enclosing <xo-view>: a tile grid, a thread list. The same pager <xo-table page-size> draws.

Attributes

Example

<xo-view get="listPeople">
  <ul><li xo-each="items">{name}</li></ul>
  <xo-pager page-size="12" page-sizes="12,24,48"></xo-pager>
</xo-view>

Guide Recipes

<xo-tabs>

@xoong/controls import '@xoong/controls';

Accessible tabs from the sections that have xo-tab. Panels stay in the DOM, so form controls on other tabs still count; xo-reveal selects the tab of an invalid field.

Attributes

Events

• xo-tab-change Another tab was selected.

Example

<xo-tabs label="Person">
  <section xo-tab="General" id="general"><label>Name <input name="name"></label></section>
  <section xo-tab="Topics" id="topics">…</section>
</xo-tabs>

Guide Tabs

<xo-menu>

@xoong/controls import '@xoong/controls';

An action menu: a trigger button and items (buttons or links) with arrow keys, Home/End, type-ahead and Escape. Drawn in the top layer where the browser supports the Popover API. Items with a value make it a choice menu: xo-menu-select fires with the value.

Attributes

Events

• xo-menu-select An item of a choice menu was chosen.
• xo-menu-open A menu opened.
• xo-menu-close A menu closed.

Example

<xo-menu label="Actions">
  <button xo-menu-trigger>Actions</button>
  <button>Duplicate</button>
  <a href="/people/1">Open</a>
</xo-menu>

Guide Menu and tooltip

<xo-combobox>

@xoong/controls import '@xoong/controls';

A form control to pick from a list you can filter by typing. <option> children are the choices; multiple shows chips; the value is a string, or an array with multiple.

Attributes

Events

• xo-search The person typed in a combobox that does not filter by itself.

Example

<xo-combobox name="topics" label="Topics" multiple>
  <option value="web">Web</option>
  <option value="data">Data</option>
  <option value="design">Design</option>
</xo-combobox>

Guide Combobox and tags

<xo-tags>

@xoong/controls import '@xoong/controls';

A free-text tag input: type and press Enter or a comma to add a chip; Backspace removes the last. Value: an array of strings.

Attributes

Example

<xo-tags name="keywords" label="Keywords" placeholder="Add a keyword"></xo-tags>

Guide Combobox and tags

<xo-richtext>

@xoong/richtext import '@xoong/richtext';

A rich text editor form control: toolbar, headings, bold, italic, lists, quote, links. The value is sanitised HTML (p, h2, h3, strong, em, ul, ol, li, blockquote, br, a, img). xo-pick-media (cancelable) asks the app for an image.

Attributes

Events

• xo-pick-media The image tool of the editor was used.
• xo-richtext-expand The editor opened in its large dialog.
• xo-richtext-done The large editor dialog was closed.

Example

<xo-richtext name="bio" label="Bio" toolbar="compact" maxlength="2000" media></xo-richtext>

Guide Rich text

<xo-carousel>

@xoong/controls import '@xoong/controls';

A row of slides you move through: cards, a banner, a gallery. The children are the slides; they sit in a scroll container with scroll snap, so swiping is native. WAI-ARIA carousel pattern, slides out of view are inert.

Attributes

Events

• xo-carousel-change The carousel moved to another slide.

Example

<xo-carousel label="Services" items="3" dots counter loop>
  <article>First</article>
  <article>Second</article>
  <article>Third</article>
  <article>Fourth</article>
</xo-carousel>

Guide Carousel

<xo-switch>

@xoong/controls import '@xoong/controls';

One setting on or off (WAI-ARIA switch). A form control with a boolean value; the text inside is the visible label (label.xo-switch-row); change fires when the person toggles it.

Attributes

Example

<xo-switch name="notify" checked>Email me about new comments</xo-switch>

Guide More controls

<xo-date>

@xoong/controls import '@xoong/controls';

A date field with a calendar popover. The value is ISO YYYY-MM-DD (with range: { start, end }); the field shows the locale format and accepts typing.

Attributes

Example

<xo-date name="publishedAt" label="Publish on" value="2026-11-25"></xo-date>

Guide More controls

<xo-time>

@xoong/controls import '@xoong/controls';

A time of day as two selects, hour and minute. The value is HH:mm or empty.

Attributes

Example

<xo-time name="at" label="Time" step="15" value="09:30"></xo-time>

Guide More controls

<xo-slider>

@xoong/controls import '@xoong/controls';

A number on a track (a native range input). input while dragging, change on release.

Attributes

Example

<xo-slider name="quality" label="Image quality" min="0" max="100" step="5" value="80"></xo-slider>

Guide More controls

<xo-stepper>

@xoong/controls import '@xoong/controls';

A number with minus and plus buttons; arrows change by step, Page by ten steps, the value is clamped.

Attributes

Example

<xo-stepper name="perPage" label="Items per page" min="1" max="100" step="5" value="25"></xo-stepper>

Guide More controls

<xo-password>

@xoong/controls import '@xoong/controls';

A password field with a show/hide button.

Attributes

Example

<xo-password name="password" label="Password" autocomplete="new-password"></xo-password>

Guide More controls

<xo-copy>

@xoong/controls import '@xoong/controls';

A read-only value with a Copy button; fires copied.

Attributes

Events

• copied The text was copied to the clipboard.
• copy-failed The browser refused the clipboard.

Example

<xo-copy label="API key" value="xo_live_4f9a7f3a"></xo-copy>

Guide More controls

<xo-image>

@xoong/controls import '@xoong/controls';

An image that loads lazily, keeps its space (no layout jump), shows a placeholder while loading and a fallback on error. data-state: empty, loading, loaded, error.

Attributes

Example

<xo-image src="img/landscape.svg" alt="A landscape" ratio="16/9" fallback="img/placeholder.svg"></xo-image>

Guide More controls

<xo-theme-toggle>

@xoong/controls import '@xoong/controls';

A button that switches between the light and the dark theme: sets data-theme on <html>, saves the choice, follows the system until chosen. Fires xo-theme-change.

Attributes

Events

• xo-theme-change The theme was switched.

Example

<xo-theme-toggle></xo-theme-toggle>

Guide More controls

<xo-accordion>

@xoong/controls import '@xoong/controls';

A stack of native <details> as an accordion; single allows one open at a time; arrows move between summaries. Fires xo-accordion-change.

Attributes

Events

• xo-accordion-change A section of an accordion opened or closed.

Example

<xo-accordion single>
  <details><summary>Does it need a build?</summary><div class="xo-accordion__body">No.</div></details>
  <details><summary>Can I use my own styles?</summary><div class="xo-accordion__body">Yes.</div></details>
</xo-accordion>

Guide More controls

<xo-popover>

@xoong/controls import '@xoong/controls';

A small panel opened by a button: Escape or an outside click closes it and the focus returns to the trigger. xo-popover-open / xo-popover-close.

Attributes

Events

• xo-popover-open A popover opened.
• xo-popover-close A popover closed.

Example

<div class="xo-notify">
  <button aria-label="Notifications">Bell</button>
  <xo-popover label="Notifications"><p>Nothing new.</p></xo-popover>
</div>

Guide More controls

<xo-consent>

@xoong/controls import '@xoong/controls';

A cookie consent bar that remembers the choice. The text inside is the message. Fires xo-consent with the choices.

Attributes

Events

• xo-consent The visitor made a choice about cookies.

Example

<xo-consent categories="analytics,marketing">
  <b>We use two cookies.</b> One keeps you signed in, one measures anonymous visits.
</xo-consent>
<button xo-consent-open>Cookie settings</button>

Guide More controls

<xo-file>

@xoong/controls import '@xoong/controls';

A file field with a drop zone. The value is a File (an array with multiple). Refused files fire xo-file-reject.

Attributes

Events

• xo-file-reject A file was refused.

Example

<xo-file name="logo" label="Logo" accept="image/*" max-size="2MB" hint="PNG or SVG, up to 2 MB"></xo-file>

Guide More controls

<xo-command>

@xoong/controls import '@xoong/controls';

A command palette: Ctrl/Cmd+K, type to filter, arrows, Enter. The children (links, buttons with data-group) are the commands. Fires xo-command-run.

Attributes

Events

• xo-command-run A command of the palette was run.

Example

<xo-command shortcut="k" label="Search commands">
  <a href="/articles" data-group="Go to">Articles</a>
  <button data-group="Actions" data-value="new-article">New article</button>
</xo-command>

Guide More controls

<xo-chart>

@xoong/controls import '@xoong/controls';

A bar or line chart drawn from data, with a table of the same numbers.

Attributes

Example

<xo-chart type="bar" label="Visits per day" unit="k" data='[{"label":"Mon","value":12},{"label":"Tue","value":18},{"label":"Wed","value":9}]'></xo-chart>

Guide More controls

<xo-range-slider>

@xoong/controls import '@xoong/controls';

A minimum and a maximum on one track: two native range inputs, thumbs cannot cross. The value is [min, max]; the attribute is value="20,70".

Attributes

Example

<xo-range-slider name="price" label="Price" min="0" max="100" value="20,70" min-label="Minimum price" max-label="Maximum price"></xo-range-slider>

Guide More controls

<xo-segmented>

@xoong/controls import '@xoong/controls';

A group of buttons where one is chosen. The children <button value> are the segments; aria-pressed on each; arrows move the focus.

Attributes

Example

<xo-segmented name="period" label="Billing period" value="month">
  <button value="month">Monthly</button>
  <button value="year">Yearly</button>
</xo-segmented>

Guide More controls

<xo-split-button>

@xoong/controls import '@xoong/controls';

A main action with a menu of related actions. The first child is the main button; the others are the menu items.

Attributes

Example

<xo-split-button more="More publish options">
  <button class="primary">Publish</button>
  <button>Schedule</button>
  <button>Save as draft</button>
</xo-split-button>

Guide More controls

<xo-textarea>

@xoong/controls import '@xoong/controls';

A textarea with a character counter and a thin progress bar toward maxlength; over the limit it is invalid and the text is kept.

Attributes

Example

<xo-textarea name="excerpt" label="Excerpt" maxlength="160" rows="3"></xo-textarea>

Guide More controls

<xo-stat>

@xoong/controls import '@xoong/controls';

A KPI tile: label, value, a change against before and a sparkline from a series.

Attributes

Example

<xo-stat label="Visits" value="48,210" delta="12.4" delta-label="vs last week" series="20,22,18,26,24,32,29"></xo-stat>

Guide More controls

<xo-otp>

@xoong/controls import '@xoong/controls';

One-time code: one box per digit; the value is the digit string; fires complete when all are filled. Paste splits across the boxes.

Attributes

Events

• complete Every box of a one-time code is filled.

Example

<xo-otp name="code" length="6" label="Verification code"></xo-otp>

Guide More controls

<xo-avatar>

@xoong/controls import '@xoong/controls';

A round badge with initials from the name, or a picture; aria-label is the name and the status.

Attributes

Example

<xo-avatar name="Linh Phạm" status="ok"></xo-avatar>

Guide More controls

<xo-avatars>

@xoong/controls import '@xoong/controls';

A stack of avatars with a +N badge for the rest; a list.

Attributes

Example

<xo-avatars max="2" label="Reviewers">
  <xo-avatar name="An Lê"></xo-avatar>
  <xo-avatar name="Binh Vo"></xo-avatar>
  <xo-avatar name="Chi Do"></xo-avatar>
</xo-avatars>

Guide More controls

<xo-progress>

@xoong/controls import '@xoong/controls';

A progress bar; no value means indeterminate.

Attributes

Example

<xo-progress value="62" label="Upload"></xo-progress>

Guide More controls

<xo-spinner>

@xoong/controls import '@xoong/controls';

A loading spinner, role=status; label="" makes it decorative.

Attributes

Example

<xo-spinner label="Loading" size="lg"></xo-spinner>

Guide More controls

<xo-steps>

@xoong/controls import '@xoong/controls';

Progress through a flow of steps: the children are the step titles; aria-current=step marks the current one; done steps show a check.

Attributes

Example

<xo-steps current="1" label="Checkout">
  <span>Account</span><span>Plan</span><span>Payment</span>
</xo-steps>

Guide More controls

<xo-inline-edit>

@xoong/controls import '@xoong/controls';

Text you rename in place: select it or press the Rename button; Enter saves, Escape cancels. Fires save and cancel.

Attributes

Events

• save The new text of an inline edit was saved.
• cancel An inline edit was cancelled.

Example

<xo-inline-edit name="title" value="Greece Golden Visa" label="Title"></xo-inline-edit>

Guide More controls

<xo-drawer>

@xoong/controls import '@xoong/controls';

A side sheet on a native modal <dialog>: open it with xo-open="#id" like xo-dialog, close it with xo-close, Escape or (with dismiss) a click outside. The header and the footer (slot="footer") stay put, the body scrolls; full screen on a phone.

Attributes

Example

<button xo-open="#filters">Filters</button>
<xo-drawer id="filters" heading="Filters" side="end" dismiss>
  <p>Choose what to show.</p>
  <button slot="footer" type="button" xo-close>Close</button>
</xo-drawer>

Guide More controls

<xo-breadcrumb>

@xoong/controls import '@xoong/controls';

The trail of pages that led here: <a> children or JSON items, the last is aria-current=page; the middle collapses into an "…" menu when max is set or the space is short.

Attributes

Example

<xo-breadcrumb max="3" items='[{"label":"Home","href":"/"},{"label":"Docs","href":"/docs"},{"label":"Controls","href":"/docs/controls"},{"label":"Tree"}]'></xo-breadcrumb>

Guide More controls

<xo-alert>

@xoong/controls import '@xoong/controls';

A message that stays in the page: an icon by kind, an optional heading and action (slot="action"), a Close button with dismissible. role=alert for warning and danger, status otherwise. Fires xo-dismiss.

Attributes

Events

• xo-dismiss The Close button of an alert was pressed.

Example

<xo-alert kind="warning" heading="Your trial ends in 3 days" dismissible>Add a payment method to keep your pages.</xo-alert>

Guide More controls

<xo-skeleton>

@xoong/controls import '@xoong/controls';

A grey placeholder in the shape of what is loading: lines of text, a circle or a rectangle. Hidden from screen readers, with one visually hidden "Loading" status; the shimmer stops under reduced motion.

Attributes

Example

<xo-skeleton lines="3"></xo-skeleton>

Guide More controls

<xo-tree>

@xoong/controls import '@xoong/controls';

A tree view (the WAI-ARIA tree pattern): nested <ul> or JSON data; arrows, Home, End, * and type-ahead; selectable or multiple (checkboxes, a parent is true, false or mixed). Fires xo-tree-select, xo-tree-toggle and, for lazy items, xo-tree-load.

Attributes

Events

• xo-tree-select The choice in a tree changed.
• xo-tree-toggle A tree item opened or closed.
• xo-tree-load A lazy tree item was opened for the first time.

Example

<xo-tree label="Files" selectable>
  <ul><li>src<ul><li>index.js</li><li>util.js</li></ul></li><li>README.md</li></ul>
</xo-tree>

Guide More controls

<xo-color>

@xoong/controls import '@xoong/controls';

A color field: a swatch button opens a panel with the native color picker, a validated hex field and preset swatches. The value is #rrggbb (#rrggbbaa with alpha).

Attributes

Example

<xo-color name="brand" label="Brand color" value="#0b7285" swatches="#0b7285,#c92a2a,#2b8a3e"></xo-color>

Guide More controls

<xo-rating>

@xoong/controls import '@xoong/controls';

A star rating: one native radio per star (two with half), so arrows, Tab and screen readers work; the pointer previews; the value is a number (0 is nothing).

Attributes

Example

<xo-rating name="score" label="Your rating" value="4" half clearable></xo-rating>

Guide More controls

xo-each

Read data @xoong/data

Repeat this element for each item of the list at the given path (keyed by entity id).

Applies to

Any element inside <xo-view>. On a <template> it repeats the template's children.

Value

The path of a list: items, tags, blocks.

• Inside it {path} reads the current item, $index is its position from 0 and $n from 1.
• Rows are keyed by entity id, so a changed list updates the rows that changed.

Example

<xo-view get="listPeople">
  <ul><li xo-each="items">{$n}. {name}</li></ul>
</xo-view>

Guide Data and tables

xo-if

Read data @xoong/data

Render this element only when the path is truthy. Prefix with ! to negate. An empty array is false.

Applies to

Any element inside <xo-view>.

Value

A path ($loading, items), !path to negate, or a comparison with a text: type=image, status!=draft.

Example

<xo-view get="listPeople">
  <p xo-if="$loading">Loading…</p>
  <p xo-if="!items">Nobody here yet.</p>
</xo-view>

Guide Loading, empty and error

xo-param

Read data @xoong/data

On an <input> or <select>: set the view parameter of that name to its value. On other elements, on click, set a view parameter and refetch: name=value, name+=n, name-=n, or name~=value (toggle value / -value, for sorting).

Applies to

An <input> or <select> (its value), or any element that is clicked (name=value), inside <xo-view>.

Value

On a field: the parameter name. On click: name=value, name+=n, name-=n (never below 0) or name~=value (toggle value and -value, for sorting).

• A button whose xo-param matches the current value gets aria-current.

Example

<xo-view get="listPeople" url-params="name,role">
  <input type="search" xo-param="name" aria-label="Search by name">
  <button xo-param="role=admin">Admins</button>
  <button xo-param="role=editor">Editors</button>
  <ul><li xo-each="items">{name}</li></ul>
</xo-view>

Guide Data and tables

xo-refresh

Read data @xoong/data

On a button inside an <xo-view>: on click, fetch the view's data again (a "Try again" button after an error, or a refresh button).

Applies to

A button inside <xo-view>.

Value

None.

Example

<xo-view get="listPeople">
  <p xo-if="$error">Could not load. <button xo-refresh>Try again</button></p>
</xo-view>

Guide Loading, empty and error

xo-click

Actions @xoong/data

Call an operation when clicked: "METHOD /path/{param}" or an operationId. Params come from the current item, then the view's p-* params.

Applies to

A <button> or link inside <xo-view>. Another element works, but it is not reachable by keyboard.

Value

An operationId (deletePerson) or METHOD /path/{param}. {param} comes from the current item, then the view's p-* parameters.

• An operation that reads (GET) belongs on <xo-view get>, not on xo-click.
• After success the queries that overlap the path are refetched.

Example

<xo-view get="listPeople">
  <ul>
    <li xo-each="items">{name}
      <button xo-click="deletePerson" xo-confirm="Delete {name}?" xo-notice="Deleted">Delete</button>
    </li>
  </ul>
</xo-view>

Guide Data and tables

xo-submit

Actions @xoong/data

On a <form>: send the form fields as the request body of the operation. The form is reset on success unless xo-keep is present. Field errors from the server appear beside the inputs.

Applies to

A <form> inside <xo-view>.

Value

An operationId or METHOD /path/{param}.

• The field names are paths (name, title.en, items[0].x). The form is reset after success unless xo-keep is present.

Example

<xo-view>
  <form xo-submit="createPerson" xo-notice="Person added">
    <label>Name <input name="name" required></label>
    <label>E-mail <input name="email" type="email"></label>
    <button>Add</button>
  </form>
</xo-view>

Guide Forms

xo-body

Actions @xoong/data

With xo-click: take the request body from the item at this path.

Applies to

An element with xo-click.

Value

The path of the object to send: . (the current item), draft, $selected.

Example

<xo-view get="listPeople">
  <ul><li xo-each="items">{name}
    <button xo-click="updatePerson" xo-body=".">Save</button>
  </li></ul>
</xo-view>

xo-keep

Actions @xoong/data

With xo-submit: keep the field values after a successful send.

Applies to

A <form> that has xo-submit.

Value

None.

Example

<xo-view>
  <form xo-submit="createPerson" xo-keep>
    <input name="name" aria-label="Name">
    <button>Add</button>
  </form>
</xo-view>

xo-optimistic

Actions @xoong/data

On xo-click: set these fields (field=value,field2={path}) on the current item immediately, and undo them if the call fails.

Applies to

An element with xo-click, inside xo-each.

Value

A list field=value,field2={path}.

Example

<xo-view get="listPeople">
  <ul><li xo-each="items">{name} ({role})
    <button xo-click="updatePerson" xo-with="role=viewer" xo-optimistic="role=viewer">Make viewer</button>
  </li></ul>
</xo-view>

Guide Data and tables

xo-select

Actions @xoong/data

On a checkbox in a row (inside xo-each): tick that row. all:items in the header ticks every row of the list. <xo-table selectable> does this for you.

Applies to

A checkbox in a row (inside xo-each), or in the header.

Value

None on a row; all:items (all: and the list path) on the header checkbox ticks every row.

• <xo-table selectable> adds these checkboxes for you.

Example

<xo-view get="listPeople">
  <label><input type="checkbox" xo-select="all:items"> All</label>
  <ul><li xo-each="items"><label><input type="checkbox" xo-select> {name}</label></li></ul>
  <button xo-click="deletePerson" xo-selected xo-if="$selectedCount">Delete {$selectedCount}</button>
</xo-view>

Guide Data and tables

xo-selected

Actions @xoong/data

On an xo-click button: run the operation once for every ticked row, one after another; the first failure stops the rest. With a value (xo-selected="ids"): ONE request whose body has the ticked ids in that field.

Applies to

An element with xo-click.

Value

None: run the operation once per ticked row. With a field name (ids): one request whose body has the ticked ids in that field.

Example

<xo-view get="listPeople">
  <ul><li xo-each="items"><label><input type="checkbox" xo-select> {name}</label></li></ul>
  <button xo-click="deletePerson" xo-selected>Delete ticked</button>
</xo-view>

Guide Data and tables

xo-with

Actions @xoong/data

On xo-click/xo-submit: fixed fields added to the request body, field=value,other={path} (typed from the request schema).

Applies to

An element with xo-click or xo-submit, or xo-add in a form.

Value

A list field=value,other={path}. Values are typed from the request schema.

Example

<xo-view get="listPeople">
  <ul><li xo-each="items">{name}
    <button xo-click="updatePerson" xo-with="role=admin">Make admin</button>
  </li></ul>
</xo-view>

Guide Data and tables

xo-confirm

Actions @xoong/data

On xo-click/xo-submit: ask before running, with a native dialog. {path} names the item: xo-confirm="Delete {title}?".

Applies to

An element with xo-click or xo-submit.

Value

The question; {path} names the item: Delete {name}?.

• The dialog is native. With @xoong/ui imported it is the built-in confirm dialog; xo-confirm-title, xo-confirm-ok, xo-confirm-cancel and xo-confirm-kind tune it.
• In JavaScript the same question is confirm().

Example

<xo-view get="listPeople">
  <ul><li xo-each="items">{name}
    <button xo-click="deletePerson" xo-confirm="Delete {name}?" xo-confirm-title="Delete person" xo-confirm-ok="Delete" xo-confirm-kind="danger">Delete</button>
  </li></ul>
</xo-view>

Guide Dialogs and modals

xo-notice

Actions @xoong/data

On xo-click/xo-submit: after success, show this message in <xo-toast> ({path} and {$selectedCount} work).

Applies to

An element with xo-click or xo-submit.

Value

The message; {path} and {$selectedCount} work.

• The message is shown by <xo-toast>. It travels as the xo-notice event.

Example

<button xo-click="deletePerson" xo-notice="Deleted {name}">Delete</button>

Guide Dialogs and modals

xo-then

Actions @xoong/data

On xo-click/xo-submit: after success, go to this path; {id} comes from the result (a created record), then from the item acted on: xo-then="/articles/{id}", or xo-then="/articles" after a delete. <xo-router> navigates.

Applies to

An element with xo-click or xo-submit.

Value

A path of this site. {id} comes from the result (a created record), then from the item acted on.

• <xo-router> navigates. Without a router the page is loaded with location.assign. Only a relative path or a same-origin URL is followed.

Example

<xo-view>
  <form xo-submit="createPerson" xo-then="/people/{id}">
    <input name="name" aria-label="Name">
    <button>Create</button>
  </form>
</xo-view>

xo-confirm-title

Actions @xoong/ui

With xo-confirm: a heading for the question (xo-confirm-title="Delete person").

Applies to

An element that has xo-confirm.

Value

The heading text.

Example

<button xo-click="deletePerson" xo-confirm="This cannot be undone." xo-confirm-title="Delete person">Delete</button>

Guide Dialogs and modals

xo-confirm-ok

Actions @xoong/ui

With xo-confirm: the text of the confirming button (xo-confirm-ok="Delete") instead of "Confirm".

Applies to

An element that has xo-confirm.

Value

The text of the confirming button.

Example

<button xo-click="deletePerson" xo-confirm="Delete {name}?" xo-confirm-ok="Delete">Delete</button>

Guide Dialogs and modals

xo-confirm-cancel

Actions @xoong/ui

With xo-confirm: the text of the cancelling button instead of "Cancel".

Applies to

An element that has xo-confirm.

Value

The text of the cancelling button.

Example

<button xo-click="deletePerson" xo-confirm="Delete {name}?" xo-confirm-cancel="Keep it">Delete</button>

xo-confirm-kind

Actions @xoong/ui

With xo-confirm: danger, warning, info or success: an icon and the matching colour; the confirming button is red unless a kind says otherwise.

Applies to

An element that has xo-confirm.

Value

One of danger, warning, info, success.

Values

danger, warning, info, success

Example

<button xo-click="updatePerson" xo-confirm="Publish now?" xo-confirm-kind="info">Publish</button>

Guide Dialogs and modals

xo-add

Form rows @xoong/forms

In a form: append an item to the array at this path (blocks); xo-with="type=image" gives a union item its tag.

Applies to

A button inside a <form xo-submit>.

Value

The path of the array: keywords, blocks. Add xo-with="type=image" to give a union item its tag.

Example

<xo-view get="getPerson" p-id="1">
  <form xo-submit="updatePerson">
    <div xo-each="keywords"><input name="keywords[{$index}]" aria-label="Keyword"></div>
    <button type="button" xo-add="keywords">Add keyword</button>
  </form>
</xo-view>

Guide Forms

xo-remove

Form rows @xoong/forms

In a form row: remove the array item at this path (blocks[{$index}]).

Applies to

A button inside a row of an array in a form.

Value

The path of the item: keywords[{$index}].

Example

<xo-view get="getPerson" p-id="1">
  <form xo-submit="updatePerson">
    <div xo-each="keywords"><input name="keywords[{$index}]" aria-label="Keyword">
      <button type="button" xo-remove="keywords[{$index}]" aria-label="Remove">✕</button></div>
  </form>
</xo-view>

Guide Forms

xo-move

Form rows @xoong/forms

In a form row: move the array item at this path, blocks[{$index}]:up or :down.

Applies to

A button inside a row of an array in a form.

Value

The path of the item and a direction: keywords[{$index}]:up or :down.

Example

<xo-view get="getPerson" p-id="1">
  <form xo-submit="updatePerson">
    <div xo-each="keywords"><input name="keywords[{$index}]" aria-label="Keyword">
      <button type="button" xo-move="keywords[{$index}]:up" aria-label="Move up">↑</button>
      <button type="button" xo-move="keywords[{$index}]:down" aria-label="Move down">↓</button></div>
  </form>
</xo-view>

Guide Forms

xo-drag

Form rows @xoong/forms

On a handle inside an array row of a form: drag the row onto another row of the same list to move it (blocks[{$index}]). The xo-move buttons stay for keyboards.

Applies to

A handle inside a row of an array in a form.

Value

The path of the item: keywords[{$index}].

Example

<xo-view get="getPerson" p-id="1">
  <form xo-submit="updatePerson">
    <div xo-each="keywords"><span class="handle" xo-drag="keywords[{$index}]" title="Drag to reorder">⠿</span>
      <input name="keywords[{$index}]" aria-label="Keyword"></div>
  </form>
</xo-view>

Guide Forms

xo-guard

Form rows @xoong/ui

On a <form xo-submit>: with unsaved changes the router asks before the page is left. xo-guard="off" disables it; any other text is the question to ask.

Applies to

A <form xo-submit>.

Value

off disables the question; any other text is the question to ask.

Example

<xo-view get="getPerson" p-id="1">
  <form xo-submit="updatePerson" xo-guard="Leave without saving?">
    <input name="name" aria-label="Name"> <button>Save</button>
  </form>
</xo-view>

xo-route

Routing @xoong/ui

On a <template> inside <xo-router>: the path this route answers, for example /users/:id; * is the not-found route. The content is inert until the route matches. An empty template with src fetches that URL the first time the route (or a layout) is shown.

Applies to

A <template> inside <xo-router>.

Value

The path the route answers: /users/:id; * is the not-found route.

Example

<xo-router>
  <template xo-route="/users/:id" title="User"><xo-view get="getPerson" p-id=":id"><h1>{name}</h1></xo-view></template>
  <template xo-route="*">Not found</template>
</xo-router>

Guide Router and page lifecycle

xo-layout

Routing @xoong/ui

On a <template> inside <xo-router>: a layout (shell) that routes use with layout="name". It must contain one element with xo-outlet.

Applies to

A <template> inside <xo-router>.

Value

The name of the layout. Routes use it with layout="name".

Example

<xo-router>
  <template xo-layout="shell"><nav><a href="/users">Users</a></nav><main xo-outlet></main></template>
  <template xo-route="/users" layout="shell">Users</template>
</xo-router>

Guide Router and page lifecycle

xo-outlet

Routing @xoong/ui

In a layout: the element where the matched route content is shown. The layout stays while only this content changes.

Applies to

One element in a layout.

Value

None.

Example

<xo-router>
  <template xo-layout="shell"><header>My app</header><main xo-outlet></main></template>
  <template xo-route="/" layout="shell">Home</template>
</xo-router>

Guide Router and page lifecycle

xo-current

Routing @xoong/ui

On a link, a nav, or the router: leave aria-current as the author set it. The router then does not mark that link current.

Applies to

A link, a nav, or <xo-router>.

Value

Present. No value.

Example

<nav xo-current>
  <a href="/studio/pages" aria-current="page">Pages</a>
</nav>

Guide Router and page lifecycle

xo-open

Dialogs @xoong/ui

Open the <xo-dialog> matched by this selector, for example #add.

Applies to

A button anywhere in the page.

Value

A selector for an <xo-dialog>: #add.

Example

<button xo-open="#add">Add person</button>
<xo-dialog id="add" heading="Add person"><xo-form op="createPerson"></xo-form></xo-dialog>

Guide Dialogs and modals

xo-close

Dialogs @xoong/ui

Close the <xo-dialog> this element is in.

Applies to

A button inside an <xo-dialog>.

Value

None.

Example

<xo-dialog id="info" heading="Info">
  <p>Saved.</p>
  <button slot="footer" xo-close>Close</button>
</xo-dialog>

Guide Dialogs and modals

xo-tab

Controls @xoong/controls

On a section inside <xo-tabs>: the tab label. The section id is the tab key (its position when it has none).

Applies to

A <section> inside <xo-tabs>.

Value

The tab label. The section's id is the key of the tab (its position without one).

Example

<xo-tabs label="Page"><section xo-tab="General">…</section><section xo-tab="SEO" id="seo">…</section></xo-tabs>

Guide Tabs

xo-menu-trigger

Controls @xoong/controls

On the button of <xo-menu> that opens it (the first button when none is marked).

Applies to

A button inside <xo-menu>.

Value

None.

Example

<xo-menu label="Actions"><button xo-menu-trigger>Actions</button><button>Duplicate</button></xo-menu>

Guide Menu and tooltip

xo-tooltip

Controls @xoong/controls

On any element: a short description shown on hover and focus (and hidden on Escape). It is a description, not the accessible name.

Applies to

Any element.

Value

The text of the tooltip.

• It describes the element; it is not its accessible name, so a button without text still needs aria-label.

Example

<button xo-tooltip="Copy the link" aria-label="Copy link">Copy</button>

Guide Menu and tooltip

xo-consent-open

Controls @xoong/controls

On any element: a click shows the <xo-consent> bar again (cookie settings).

Applies to

Any element (a button).

Value

None.

Example

<button xo-consent-open>Cookie settings</button>

Guide More controls

xo-t

Language @xoong/i18n

Translate this element with @xoong/i18n: xo-t="key" for its text, xo-t="attr:key; attr2:key2" for attributes. The text written in the HTML is the default. {placeholders} come from the enclosing xo-view.

Applies to

Any element.

Value

A message key for the text (home.title), or attr:key; attr2:key2 for attributes.

• The text written in the HTML is the default. Inside an <xo-view>, {placeholders} come from the view.

Example

<h1 xo-t="home.title">Welcome</h1>
<input xo-t="placeholder:search.placeholder" placeholder="Search" aria-label="Search">

Guide Recipes

xo-done

Bubbles

An action succeeded. Fires on the element that ran the action, after the server answered, and bubbles. <xo-dialog> closes when a form inside it fires it; <xo-toast> hides its error.

Fired by

<xo-view> (xo-click, xo-submit, <xo-form>)

detail

The result of the operation.

Example

document.addEventListener('xo-done', (event) => console.log(event.detail));

xo-error

Bubbles Cancelable

A load or an action failed. Fires on the element that ran the action (or the view that could not load) and bubbles. Cancelable: call preventDefault() when your own code handles the failure, and <xo-toast> stays quiet. event.handled is true when the view shows $error itself, or the error is a 401 that onUnauthorized deals with: the toast skips those too. detail.action ({ label, run }, for example Retry) and detail.timeout are drawn when the toast is not skipped.

Fired by

<xo-view>, <xo-router>

detail

The XoongError (status, code, detail, fields). Set action ({ label, run }) and timeout on it and <xo-toast> shows that button (it reads them one microtask later).

Example

document.addEventListener('xo-error', (event) => console.log(event.detail));

xo-invalid

Bubbles

A form was not sent because it is invalid. Nothing was sent; the form already shows why beside each field.

Fired by

<form xo-submit>

detail

{ errors }: the messages by field path.

Example

document.addEventListener('xo-invalid', (event) => console.log(event.detail));

xo-notice

Bubbles

A message for the toast. Fires after an action with xo-notice succeeded, and when you call toast.show(). <xo-toast> listens on the document.

Fired by

xo-notice, toast.show()

detail

{ message, kind }; toast.show() adds action and timeout.

Example

document.addEventListener('xo-notice', (event) => console.log(event.detail));

xo-go

Bubbles Cancelable

An action asked to go to another page. Cancelable. <xo-router> handles it and cancels the default; without a router the page is loaded with location.assign.

Fired by

xo-then

detail

{ path }: where to go.

Example

document.addEventListener('xo-go', (event) => console.log(event.detail));

xo-navigate

Bubbles

The router moved to another location. Fires after a navigation, also when only the query or the hash changed.

Fired by

<xo-router>

detail

{ to, from }: two route locations (path, params, query, url, route).

Example

document.addEventListener('xo-navigate', (event) => console.log(event.detail));

xo-columns-change

Bubbles

The person showed or hid a column of the table. Fires from the Columns picker. With columns-key the choice is also remembered in this browser.

Fired by

<xo-table column-picker>

detail

{ visible, hidden }: the field names that are shown and those that are hidden.

Example

document.addEventListener('xo-columns-change', (event) => console.log(event.detail));

xo-dirty

Bubbles

A form gained or lost unsaved changes. The router listens to it to ask before the page is left.

Fired by

<form xo-submit>

detail

{ dirty }: true when there are unsaved changes.

Example

document.addEventListener('xo-dirty', (event) => console.log(event.detail));

xo-reveal

Bubbles Cancelable

The form is about to focus an invalid field. Cancelable. <xo-tabs> listens and selects the tab of the field first, so the field is visible when it gets the focus.

Fired by

<form xo-submit>

detail

{ path }: the invalid field.

Example

document.addEventListener('xo-reveal', (event) => console.log(event.detail));

xo-array-change

Bubbles

A row of an array in a form was added, removed or moved. Fires for the add, remove and move buttons, a drag, and code that changes the array.

Fired by

<form xo-submit>

detail

{ path, op, from, to }: op is add, remove or move.

Example

document.addEventListener('xo-array-change', (event) => console.log(event.detail));

xo-form-ready

Bubbles

The form model exists. From here form.model is available. A child control that needs the model listens for this event.

Fired by

<form xo-submit>

detail

{ model }: the form model.

Example

document.addEventListener('xo-form-ready', (event) => console.log(event.detail));

xo-pick-media

Bubbles Cancelable

The image tool of the editor was used. Cancelable. Open your media library in a listener, call preventDefault(), and call detail.insert now or later. Without preventDefault() nothing is inserted.

Fired by

<xo-richtext>

detail

{ insert }: call insert({ src, alt }) when the person has chosen.

Example

document.addEventListener('xo-pick-media', (event) => console.log(event.detail));

xo-richtext-expand

Bubbles

The editor opened in its large dialog.

Fired by

<xo-richtext>

detail

None.

Example

document.addEventListener('xo-richtext-expand', (event) => console.log(event.detail));

xo-richtext-done

Bubbles

The large editor dialog was closed. Fires for Done and for Escape.

Fired by

<xo-richtext>

detail

None.

Example

document.addEventListener('xo-richtext-done', (event) => console.log(event.detail));

xo-search

Bubbles

The person typed in a combobox that does not filter by itself. Set el.options in the listener.

Fired by

<xo-combobox remote>

detail

{ query }: what the person typed.

Example

document.addEventListener('xo-search', (event) => console.log(event.detail));

xo-tab-change

Bubbles

Another tab was selected.

Fired by

<xo-tabs>

detail

{ value }: the key of the selected tab.

Example

document.addEventListener('xo-tab-change', (event) => console.log(event.detail));

xo-menu-select

Bubbles

An item of a choice menu was chosen. Only for items that have a value attribute.

Fired by

<xo-menu>

detail

{ value }: the value of the chosen item.

Example

document.addEventListener('xo-menu-select', (event) => console.log(event.detail));

xo-menu-open

Bubbles

A menu opened.

Fired by

<xo-menu>

detail

None.

Example

document.addEventListener('xo-menu-open', (event) => console.log(event.detail));

xo-menu-close

Bubbles

A menu closed.

Fired by

<xo-menu>

detail

None.

Example

document.addEventListener('xo-menu-close', (event) => console.log(event.detail));

xo-carousel-change

Bubbles

The carousel moved to another slide.

Fired by

<xo-carousel>

detail

{ index, count }: the first visible slide and the number of slides.

Example

document.addEventListener('xo-carousel-change', (event) => console.log(event.detail));

xo-file-reject

Bubbles

A file was refused.

Fired by

<xo-file>

detail

{ file, reason }: reason is type or size.

Example

document.addEventListener('xo-file-reject', (event) => console.log(event.detail));

xo-command-run

Bubbles

A command of the palette was run.

Fired by

<xo-command>

detail

{ value, label }: data-value (or the href), and the text of the command.

Example

document.addEventListener('xo-command-run', (event) => console.log(event.detail));

xo-consent

Bubbles

The visitor made a choice about cookies.

Fired by

<xo-consent>

detail

The choices: one boolean per category ({ analytics: true, marketing: false }).

Example

document.addEventListener('xo-consent', (event) => console.log(event.detail));

xo-theme-change

Bubbles

The theme was switched.

Fired by

<xo-theme-toggle>

detail

{ theme }: light or dark.

Example

document.addEventListener('xo-theme-change', (event) => console.log(event.detail));

xo-popover-open

Bubbles

A popover opened.

Fired by

<xo-popover>

detail

None.

Example

document.addEventListener('xo-popover-open', (event) => console.log(event.detail));

xo-popover-close

Bubbles

A popover closed.

Fired by

<xo-popover>

detail

None.

Example

document.addEventListener('xo-popover-close', (event) => console.log(event.detail));

xo-accordion-change

Bubbles

A section of an accordion opened or closed.

Fired by

<xo-accordion>

detail

{ index, open }: which section and whether it is open now.

Example

document.addEventListener('xo-accordion-change', (event) => console.log(event.detail));

copied

Bubbles

The text was copied to the clipboard.

Fired by

<xo-copy>

detail

{ text }: what was copied.

Example

document.addEventListener('copied', (event) => console.log(event.detail));

copy-failed

Bubbles

The browser refused the clipboard.

Fired by

<xo-copy>

detail

{ text }: what could not be copied.

Example

document.addEventListener('copy-failed', (event) => console.log(event.detail));

complete

Bubbles

Every box of a one-time code is filled.

Fired by

<xo-otp>

detail

{ value }: the digits.

Example

document.addEventListener('complete', (event) => console.log(event.detail));

save

Bubbles

The new text of an inline edit was saved. Enter saves.

Fired by

<xo-inline-edit>

detail

{ value }: the new text.

Example

document.addEventListener('save', (event) => console.log(event.detail));

xo-dismiss

Bubbles

The Close button of an alert was pressed.

Fired by

<xo-alert>

detail

None. preventDefault() keeps the alert.

Example

document.addEventListener('xo-dismiss', (event) => console.log(event.detail));

xo-tree-select

Bubbles

The choice in a tree changed.

Fired by

<xo-tree>

detail

{ id, selected }: the item acted on and the chosen ids.

Example

document.addEventListener('xo-tree-select', (event) => console.log(event.detail));

xo-tree-toggle

Bubbles

A tree item opened or closed.

Fired by

<xo-tree>

detail

{ id, expanded }: the item and whether it is open now.

Example

document.addEventListener('xo-tree-toggle', (event) => console.log(event.detail));

xo-tree-load

Bubbles

A lazy tree item was opened for the first time.

Fired by

<xo-tree>

detail

{ id }: the lazy item; answer with tree.setChildren(id, children).

Example

document.addEventListener('xo-tree-load', (event) => console.log(event.detail));

cancel

Bubbles

An inline edit was cancelled. Escape cancels.

Fired by

<xo-inline-edit>

detail

None.

Example

document.addEventListener('cancel', (event) => console.log(event.detail));

configure(options)

@xoong/data import { configure } from '@xoong/data';

Every <xo-view>, xo-click and xo-submit uses this client. Call it before the views start; views that started earlier wait for it.

Returns

Client

Parameters

Example

import { configure } from '@xoong/data';
import '@xoong/data/view';
import operations from '/.xoong/operations.json' with { type: 'json' };

configure({ api: operations, baseUrl: '/api', streamUrl: '/api/events' });

function configure<Ops extends Record<keyof Ops, OperationType> = any>(options: ClientOptions): Client<Ops>;

Guide Install

getClient()

@xoong/data import { getClient } from '@xoong/data';

Use it when HTML is not enough: getClient().load(...), .mutate(...), .reset().

Returns

Client

Example

import { getClient } from '@xoong/data';

const people = await getClient().load('listPeople', { limit: 5 });

function getClient<Ops extends Record<keyof Ops, OperationType> = any>(): Client<Ops>;

Guide Install

createClient(options)

@xoong/data import { createClient } from '@xoong/data';

Takes the same options as configure(). Useful in tests and for a second API.

Returns

Client

Parameters

Example

import { createClient } from '@xoong/data';

const client = createClient({ api: operations, baseUrl: '/api' });

function createClient<Ops extends Record<keyof Ops, OperationType> = any>(options: ClientOptions): Client<Ops>;

client.load(operation, params?)

@xoong/data const client = getClient();

Uses the cache while the result is fresh (staleTime). Throws a XoongError when the request fails.

Returns

Promise<response>

Parameters

Example

const page = await getClient().load('listPeople', { limit: 10, sort: 'name' });

load<K extends Id<Ops>>(op: K, ...params: ParamsArg<Ops[K]>): Promise<Ops[K]['response']>;

Guide Data and tables

client.query(operation, params?)

@xoong/data const client = getClient();

data, status (idle, loading, success, error) and error are signals: read them inside an effect or a template. retain() and release() keep the query alive while you observe it.

Returns

{ data, status, error, retain(), release(), invalidate(), fetch() }

Parameters

Example

const query = getClient().query('listPeople', { limit: 5 });
query.retain();
effect(() => console.log(query.status.value, query.data.value));

query<K extends Id<Ops>>(op: K, ...params: ParamsArg<Ops[K]>): TypedQuery<Ops[K]>;

client.mutate(operation, params, body?)

@xoong/data const client = getClient();

Resolves with the response. The queries whose path overlaps the mutation are refetched afterwards (see invalidate in configure).

Returns

Promise<response>

Parameters

Example

await getClient().mutate('createPerson', {}, { name: 'Ada Lovelace', email: 'ada@example.org' });

mutate<K extends Id<Ops>>(op: K, params: Ops[K]['params'], ...body: [Ops[K]['body']] extends [never] ? [] : [body: Ops[K]['body']]): Promise<Ops[K]['response']>;

Guide Data and tables

client.seed(operation, params, data)

@xoong/data const client = getClient();

As if the GET had run: no request is made until the result is stale. For data embedded in the page.

Returns

the data

Parameters

Example

getClient().seed('listPeople', { limit: 5 }, { items: [], total: 0 });

seed<K extends Id<Ops>>(op: K, params: Ops[K] extends { params: infer P } ? P : never, data: Ops[K]['response']): Ops[K]['response'];

client.stream(operation, params, body?, { signal }?)

@xoong/data const client = getClient();

Each event is { event, data, json, id }; json is data parsed when it is JSON. Pass an AbortSignal to stop.

Returns

AsyncGenerator<SseEvent>

Parameters

Example

for await (const event of getClient().stream('sendMessage', {}, { text: 'Hello' })) {
  console.log(event.json ?? event.data);
}

stream<K extends Id<Ops>>(op: K, params: Ops[K]['params'], body?: Ops[K]['body'], options?: { signal?: AbortSignal }): AsyncGenerator<SseEvent>;

client.invalidateAll()

@xoong/data const client = getClient();

Views on screen fetch again.

Returns

void

Example

getClient().invalidateAll();

invalidateAll(): void;

client.reset()

@xoong/data const client = getClient();

For a logout or another user: requests in flight are cancelled, cached queries and entities are dropped, and what a mounted view shows is fetched again. Mutations already sent are not cancelled.

Returns

void

Example

configure({ api: operations, onUnauthorized: () => { getClient().reset(); router.navigate('/login'); } });

reset(): void;

derived(({ all, get }) => value, client?)

@xoong/data import { derived } from '@xoong/data';

all('Order') lists every loaded entity of a type, get(name, id) returns one. It recomputes when they change and never makes a request: fetching is declared on a view.

Returns

Signal

Example

import { derived } from '@xoong/data';

const openOrders = derived(({ all }) => all('Order').filter((o) => o.status === 'open').length);

function derived<T>(fn: (ctx: { all(name: string): any[]; get(name: string, id: string | number): any }) => T, client?: Client<any>): Signal<T>;

connectStream({ client, url, EventSource?, onStatus?, onError? })

@xoong/data import { connectStream } from '@xoong/data';

The events are patch, upsert, delete and resync. configure({ streamUrl }) does this for you when a view has live.

Returns

{ close() }

Example

import { connectStream, getClient } from '@xoong/data';

const stream = connectStream({ client: getClient(), url: '/api/events' });

function connectStream(options: { client: Client<any>; url: string; EventSource?: typeof EventSource; onStatus?: (s: 'open' | 'error' | 'closed') => void; onError?: (e: Error) => void }): { close(): void };

class XoongError extends Error

@xoong/data import { XoongError } from '@xoong/data';

Built from problem+json or { error: { code, message } }. Fields: status, title, detail, code, retryAfterS, operation, and fields, the messages by field ({ email: 'is not valid' }).

Example

document.addEventListener('xo-error', (event) => console.warn(event.detail.status, event.detail.detail));

class XoongError extends Error {
  status: number;
  title?: string;
  detail?: string;
  code?: string;
  retryAfterS?: number;
  problem?: any;
  operation?: string;
  /** Per-field messages when the server reports them (`{ email: 'is not valid' }`). */
  fields: Record<string, string>;
}

setFormat(name, fn)

@xoong/data import { setFormat } from '@xoong/data/view';

Then {price | currency} works in any view. The function receives the value and the active language. A format that throws shows the plain value.

Returns

void

Parameters

Example

import { setFormat } from '@xoong/data/view';

setFormat('currency', (value, locale) => new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' }).format(value));

export function setFormat(name: string, fn: (value: any, locale?: string) => string): void

Guide Recipes

confirm(message, options?)

@xoong/ui import { confirm } from '@xoong/ui';

The built-in dialog, a native modal. Without a kind the confirming button is red, as for something that cannot be undone. Escape answers false.

Returns

Promise<boolean>

Parameters

Example

import { confirm } from '@xoong/ui';

if (await confirm('Delete 3 items?', { kind: 'danger', ok: 'Delete' })) remove();

function confirm(message: string, options?: DialogLook & { ok?: string; cancel?: string }): Promise<boolean>;

Guide Dialogs and modals

alert(message, options?)

@xoong/ui import { alert } from '@xoong/ui';

One button; resolves when the dialog is closed. kind defaults to info.

Returns

Promise<void>

Parameters

Example

await alert('Saved', { kind: 'success' });

function alert(message: string, options?: DialogLook & { ok?: string }): Promise<void>;

Guide Dialogs and modals

prompt(message, options?)

@xoong/ui import { prompt } from '@xoong/ui';

Resolves with the text, or null when cancelled. The field is native, so required, pattern and type are checked by the browser.

Returns

Promise<string | null>

Parameters

Example

const name = await prompt('Name this view', { value: 'My view', required: true });

function prompt(message: string, options?: DialogLook & { value?: string; label?: string; placeholder?: string; type?: string; required?: boolean; pattern?: string; ok?: string; cancel?: string }): Promise<string | null>;

Guide Dialogs and modals

ask(message, { buttons, ...look })

@xoong/ui import { ask } from '@xoong/ui';

Resolves with the value of the button pressed; Escape answers with the value of the one marked cancel, or null when none is.

Returns

Promise<unknown>

Parameters

Example

const answer = await ask('Save changes?', {
  buttons: [{ label: 'Discard', value: 'no' }, { label: 'Save', value: 'yes', primary: true }],
});

function ask(message: string, options: DialogLook & { buttons: DialogChoice[] }): Promise<unknown>;

Guide Dialogs and modals

confirmLabels.ok, confirmLabels.cancel

@xoong/ui import { confirmLabels } from '@xoong/ui';

Replace them for another wording or another language: confirmLabels.ok = 'Delete'.

Example

import { confirmLabels } from '@xoong/ui';

confirmLabels.ok = 'Yes, delete';

const confirmLabels: { ok: string; cancel: string };

Guide Dialogs and modals

setConfirm(fn)

@xoong/ui import { setConfirm } from '@xoong/ui';

For xo-confirm and the question asked when a form with unsaved changes is left. fn(message, context) returns true (or a promise of it) to go on.

Returns

void

Example

import { setConfirm } from '@xoong/ui';

setConfirm((message) => myDialog.ask(message));

function setConfirm(fn: (message: string, context?: ConfirmContext) => boolean | Promise<boolean>): void;

Guide Dialogs and modals

toast.show({ message, kind?, action?, timeout? })

@xoong/ui import { toast } from '@xoong/ui';

A message that asks nothing and may offer one action, for example Undo. It is the same notice xo-notice shows.

Returns

void

Parameters

Example

import { toast } from '@xoong/ui';

toast.show({ message: 'Published 3', action: { label: 'Undo', run: undo } });

show(notice: { message: string; kind?: string; action?: { label: string; run: () => unknown }; timeout?: number }): void;

Guide Dialogs and modals

router.navigate(path, { replace? }?)

@xoong/ui import { router } from '@xoong/ui';

The path is relative to the router's base. Resolves with true when the navigation happened (a guard or a veto may stop it).

Returns

Promise<boolean>

Parameters