# API reference

Source: http://realm.js.org/reference/

Exact names, types and defaults for everything in REALM. New to REALM? Start with the [Docs](/docs/).

All examples load REALM from the CDN:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js"></script>
```

## Elements

| Element | Purpose |
| --- | --- |
| [`<custom-element>`](/reference/elements/custom-element/) | Defines a component |
| [`<import-element>`](/reference/elements/import-element/) | Loads a file of component definitions |
| [`<repeat-list>`](/reference/elements/repeat-list/) | Repeats its content for each item of an array |
| [`<is-visible>`](/reference/elements/is-visible/) | Mounts its content while a condition is true |
| [`<is-hidden>`](/reference/elements/is-hidden/) | Mounts its content while a condition is false |
| [Value slots](/reference/elements/value-slots/) | `<slot name="#…">` and `<slot name="@…">` show a value |

## Attributes

| Attribute | Purpose |
| --- | --- |
| [`_name`](/reference/attributes/bindings/) | Binds an attribute, property or CSS variable to a reference |
| [`on…`](/reference/attributes/handlers/) | Event handlers in component markup and on plain pages |
| [`debounce`, `throttle`](/reference/attributes/debounce-throttle/) | Delay or rate-limit handlers and requests |
| [`ref`](/reference/attributes/ref/) | Names an element for `refs` and `render` |
| [`repeat`](/reference/attributes/repeat/) | Repeats one element per item |
| [`focusgroup`](/reference/attributes/focusgroup/) | Arrow-key focus navigation |
| [`fetch`, `method`, `params`, `headers`](/reference/fetch/fetch/) | Send a request from markup |
| [`trigger`, `poll`](/reference/fetch/trigger/) | When the request is sent |
| [`into`, `into-mode`, `into-key`](/reference/fetch/into/) | Write the response into state |
| [`render`, `render-mode`, `render-select`](/reference/fetch/render/) | Insert the response as HTML |
| [`busy`, `timeout`](/reference/fetch/busy-timeout/) | Track a request and set a time limit |

## Script

Names available in every component `<script>` without importing. See [Component script](/reference/script/) for how scripts run.

| Props and state | Element | Lifecycle |
| --- | --- | --- |
| [`defineProps`](/reference/script/define-props/) | [`host`](/reference/script/host/) | [`onConnected`](/reference/script/on-connected/) |
| [`prop`](/reference/script/prop/) | [`refs`](/reference/script/refs/) | [`onDisconnected`](/reference/script/on-disconnected/) |
| [`useState`](/reference/script/use-state/) | [`signal`](/reference/script/signal/) | [`onFormReset`](/reference/script/on-form-reset/) |
| [`observe`](/reference/script/observe/) | [`internals`](/reference/script/internals/) | [`onFormDisabled`](/reference/script/on-form-disabled/) |
| [`tick`](/reference/script/tick/) | [`attrs`](/reference/script/attrs/) | [`onFormStateRestore`](/reference/script/on-form-state-restore/) |
| [`defineStore`](/reference/script/define-store/) | [`useChildren`](/reference/script/use-children/) | |
| | [`defineMethods`](/reference/script/define-methods/) | |
| | [`dispatch`](/reference/script/dispatch/) | |
| | [`listen`](/reference/script/listen/) | |
| | [`lookup`](/reference/script/lookup/) | |
| | [Timers](/reference/script/timers/) | |

## Events, CSS and JavaScript

| Page | Covers |
| --- | --- |
| [Request events](/reference/events/request-events/) | `loadstart`, `load`, `error`, `abort`, `timeout`, `loadend` from fetch attributes |
| [Import events](/reference/events/import-events/) | `load` and `error` from `<import-element>` |
| [Component events](/reference/events/component-events/) | Events your components send, and `change` from delegated controls |
| [realm.css](/reference/css/realm-css/) | The page and shadow root stylesheet |
| [`--attr-*` and `--state-*`](/reference/css/variables/) | Reactive CSS custom properties |
| [`:state()`](/reference/css/states/) | Reactive custom states, including `:state(loading)` |
| [Design tokens](/reference/css/design-tokens/) | The REALM UI theme variables |
| [Entry points](/reference/javascript/entry-points/) | `realm.js`, `index.js`, `compiler.js` and what each exports |
| [`start`](/reference/javascript/start/), [`importDefinitions`](/reference/javascript/import-definitions/), [`defineComponent`](/reference/javascript/define-component/) | Start REALM and define components from JavaScript |
| [`flush`](/reference/javascript/flush/), [`toRaw`](/reference/javascript/to-raw/), [`untrack`](/reference/javascript/untrack/) | Reactivity utilities |
| [Compiler](/reference/javascript/compiler/) | `compileDefinition` and `tokenize` |
| [Vite plugin](/reference/tooling/vite-plugin/) | Assemble components at build time for a strict Content Security Policy |

[References and durations](/reference/syntax/) covers the value syntax all attributes share. [Console messages](/reference/console/) lists every warning REALM prints.


---

# Blog

Source: http://realm.js.org/blog/

News and release notes from the REALM project.

## Posts

- **[REALM is dead, long live REALM](/blog/realm-v2/)**, 20 October 2026. Why v1 stopped, what changed in the v2 rewrite, and how to start.
- **[Project is under maintenance mode](/blog/project-is-under-maintenance-mode/)**, 5 June 2025. Why REALM v1 stopped getting new features.
- **[Introducing Unicons by Realm](/blog/universal-web-component-icons/)**, 29 September 2023. Icons from React Icons as web components for any page.
- **[Initial Release 🎉](/blog/initial-release/)**, 9 September 2023. The first public release of REALM v1.


---

# Components

Source: http://realm.js.org/components/

REALM UI (`@realmorg/ui`) is a set of accessible components built with REALM and native HTML. Every component is a plain `<custom-element>` file you can read, copy and change. This site is built with them.

```html live
<div class="demo-narrow">
  <ui-card>
    <ui-card-header>
      <ui-card-title level="2">Create project</ui-card-title>
      <ui-card-description>Deploy your new project in one click.</ui-card-description>
    </ui-card-header>
    <ui-card-content>
      <ui-field>
        <ui-label for="project-name">Name</ui-label>
        <ui-input id="project-name" placeholder="Name of your project"></ui-input>
      </ui-field>
    </ui-card-content>
    <ui-card-footer justify="between">
      <ui-button variant="outline">Cancel</ui-button>
      <ui-button>Deploy</ui-button>
    </ui-card-footer>
  </ui-card>
</div>
```

## Installation

REALM UI needs no installation. Load REALM, the theme and the component bundle from the jsDelivr CDN, once per page:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/theme.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js"></script>

<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/ui.html"></import-element>
```

To load less, import only the components you use instead of the bundle:

```html
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/components/button.html"></import-element>
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/components/card.html"></import-element>
```

Each file imports the files it depends on, so `sheet.html` also loads `dialog.html`. A file is fetched once, however many files import it.

Pin an exact version (currently `@realmorg/ui@2.0.0-alpha.2`) in production, as described in [Installation](/docs/installation/#pin-a-version). The package contains:

| File | Contents |
| --- | --- |
| `dist/theme.css` | Design tokens (colours, spacing, type, radius, shadows) with light and dark values |
| `dist/ui.html` | Every component in one file |
| `components/<name>.html` | One component (or a small family, such as tabs and tab panels) per file, with its dependencies imported at the top |

To own a component, copy its file from `components/` into your project and import your copy instead. Components depend on REALM, the theme tokens and the files they import at the top, such as `button.html`.

## Conventions

- **Native first.** Components wrap native elements: `ui-button` renders a `<button>`, `ui-select` a `<select>`, `ui-dialog` a `<dialog>`, popovers use the Popover API.
- **Attributes are props.** Every attribute is declared with `defineProps`, typed and validated. Variants and sizes are attributes: `<ui-button variant="outline" size="sm">`.
- **Forms.** Inputs are form-associated: they submit with their `name`, reset, validate, and follow `<fieldset disabled>`.
- **Events.** Components emit native-named events where one fits (`change`, `input`, `toggle`, `select`, `close`, `cancel`), so `onchange` works on any page.
- **Styling.** Inner elements are exposed with `part`, and every component reads the theme tokens. Variants are reactive CSS states you can also target from outside, such as `ui-button:state(attr-variant-is-ghost)`.
- **Accessibility.** Roles, labels, keyboard support and focus management follow the WAI-ARIA patterns. Each page lists them.

## Theming

Override tokens on `:root` or any element. Dark mode follows the system, `data-theme="dark"` on `<html>` forces it, and `data-theme="light"` turns it off. [Theming](/components/theming/) lists every token and has a theme builder.

```css
:root {
  --radius: 0.375rem;
  --primary: oklch(0.55 0.2 260);
  --primary-foreground: oklch(0.98 0 0);
}
```

## All components

### Forms

[Button](/components/button/) · [Button Group](/components/button-group/) · [Calendar](/components/calendar/) · [Checkbox](/components/checkbox/) · [Combobox](/components/combobox/) · [Field](/components/field/) · [Input](/components/input/) · [Input Group](/components/input-group/) · [Input OTP](/components/input-otp/) · [Label](/components/label/) · [Radio Group](/components/radio-group/) · [Select](/components/select/) · [Slider](/components/slider/) · [Switch](/components/switch/) · [Textarea](/components/textarea/) · [Toggle](/components/toggle/) · [Toggle Group](/components/toggle-group/)

### Display

[Alert](/components/alert/) · [Avatar](/components/avatar/) · [Badge](/components/badge/) · [Card](/components/card/) · [Chart](/components/chart/) · [Empty](/components/empty/) · [Item](/components/item/) · [Kbd](/components/kbd/) · [Progress](/components/progress/) · [Separator](/components/separator/) · [Skeleton](/components/skeleton/) · [Spinner](/components/spinner/) · [Table](/components/table/)

### Overlays

[Alert Dialog](/components/alert-dialog/) · [Command](/components/command/) · [Context Menu](/components/context-menu/) · [Dialog](/components/dialog/) · [Drawer](/components/drawer/) · [Dropdown Menu](/components/dropdown-menu/) · [Hover Card](/components/hover-card/) · [Popover](/components/popover/) · [Sheet](/components/sheet/) · [Toaster](/components/toaster/) · [Tooltip](/components/tooltip/)

### Navigation

[Accordion](/components/accordion/) · [Breadcrumb](/components/breadcrumb/) · [Collapsible](/components/collapsible/) · [Menubar](/components/menubar/) · [Navigation Menu](/components/navigation-menu/) · [Pagination](/components/pagination/) · [Sidebar](/components/sidebar/) · [Tabs](/components/tabs/)

### Layout

[Aspect Ratio](/components/aspect-ratio/) · [Carousel](/components/carousel/) · [Direction](/components/direction/) · [Resizable](/components/resizable/) · [Scroll Area](/components/scroll-area/)

### Chat and content

[Attachment](/components/attachment/) · [Bubble](/components/bubble/) · [Code Block](/components/code-block/) · [Marker](/components/marker/) · [Message](/components/message/) · [Message Scroller](/components/message-scroller/)


---

# Examples

Source: http://realm.js.org/examples/

Each example is a complete page that runs on this site. Open one and use your browser's View Source to read it. Every example is plain HTML files plus a few small JavaScript modules, loaded with `<import-element>`. The source is in [apps/examples](https://github.com/realmorg/realm/tree/main/apps/examples) on GitHub.


## Apps

<div class="card-grid">
<a class="link-card" href="/examples/todo/"><u-icon name="list-todo"></u-icon><strong>Todo</strong><span>A store persisted to localStorage, getters for filters and counts, keyed list rows, inline editing with tick() and focus.</span></a>
<a class="link-card" href="/examples/kanban/"><u-icon name="square-kanban"></u-icon><strong>Kanban board</strong><span>Columns and cards in a persisted store, native drag and drop, keyboard moves with custom events, a card editor in a dialog.</span></a>
<a class="link-card" href="/examples/chess/"><u-icon name="crown"></u-icon><strong>Chess</strong><span>A full game with legal moves, check, mate and draws, a computer opponent, board flipping and a promotion dialog. Logic lives in an imported module.</span></a>
<a class="link-card" href="/examples/dashboard/"><u-icon name="layout-dashboard"></u-icon><strong>Dashboard</strong><span>A sidebar layout, breadcrumb, tabs, charts, a data table with pagination, a command palette and a dropdown menu, all from REALM UI.</span></a>
<a class="link-card" href="/examples/weather/"><u-icon name="cloud-sun"></u-icon><strong>Weather</strong><span>City search and a forecast from the Open-Meteo API through fetch attributes, with loading and error states, a chart and a unit switch.</span></a>
<a class="link-card" href="/examples/contacts/"><u-icon name="contact"></u-icon><strong>Contacts</strong><span>Create, read, update and delete over a JSON API (served by a service worker) with forms, fetch attributes, validation, dialogs and confirmations.</span></a>
<a class="link-card" href="/examples/chat/"><u-icon name="message-circle"></u-icon><strong>Chat</strong><span>Conversations with message bubbles, attachments and a scroller that sticks to the newest message. Replies arrive through element-bound timers, with a typing indicator and unread badges.</span></a>
<a class="link-card" href="/examples/shop/"><u-icon name="shopping-bag"></u-icon><strong>Shop</strong><span>A product list, product pages and a cart as plain HTML pages without a router, sharing one persisted store. Checkout validates its form and confirms with a dialog.</span></a>
<a class="link-card" href="/examples/notes/"><u-icon name="notebook-pen"></u-icon><strong>Notes</strong><span>Markdown notes with a live preview rendered through a sanitised html slot, search, pinning, keyboard shortcuts and a persisted store.</span></a>
<a class="link-card" href="/examples/expenses/"><u-icon name="wallet"></u-icon><strong>Expenses</strong><span>An expense form, a sortable and filterable table, monthly totals, a chart by category and a CSV export, all derived from one persisted store.</span></a>
<a class="link-card" href="/examples/github/"><u-icon name="github"></u-icon><strong>GitHub explorer</strong><span>The public GitHub API through fetch attributes only: debounced search, profiles, sorted and paginated repositories, loading skeletons and rate-limit errors.</span></a>
<a class="link-card" href="/examples/game/"><u-icon name="bomb"></u-icon><strong>Minesweeper</strong><span>Three difficulty levels, replayable seeded boards, a timer bound to the element, keyboard play, best times saved in the browser and win or lose dialogs.</span></a>
</div>

## Blocks

Page sections built from REALM UI components. All of them are defined in one file, `blocks.html`.

<div class="card-grid">
<a class="link-card" href="/examples/login/"><u-icon name="log-in"></u-icon><strong>Login</strong><span>A centred sign-in card with email and password fields, validation and a toast on submit.</span></a>
<a class="link-card" href="/examples/login-split/"><u-icon name="panels-top-left"></u-icon><strong>Login, split</strong><span>The same sign-in form beside a full-height panel, for wider screens.</span></a>
<a class="link-card" href="/examples/signup/"><u-icon name="user-plus"></u-icon><strong>Sign up</strong><span>A registration form with fields, a terms checkbox and native form validation.</span></a>
<a class="link-card" href="/examples/otp/"><u-icon name="key-round"></u-icon><strong>One-time password</strong><span>A six-digit code with Input OTP, paste support and a handler for the complete event.</span></a>
</div>

## Smaller examples in the docs

Many docs pages include live demos you can read and change:

- a counter with props and getters on the [home page](/),
- a reading list built step by step in the [Tutorial](/docs/tutorial/),
- a stopwatch with `observe` in [State and reactivity](/docs/state/),
- a keyed, shuffled list in [Lists and keys](/docs/lists/),
- a filtered page index loaded with fetch attributes in [Fetching data](/docs/fetching/),
- a form-associated quantity input in [Forms](/docs/forms/),
- reactive CSS variables and states in [Styling](/docs/styling/).


---

# Introduction

Source: http://realm.js.org/docs/

REALM is a small runtime for building native web components in HTML. A component is a single `<custom-element>` tag that holds three things: a `<script>` with plain JavaScript, a `<style>`, and markup. REALM turns it into a custom element with a shadow root. There is no compiler, no virtual DOM and no build step.

```html live stacked
<custom-element name="hello-card">
  <script type="realm">
    const props = defineProps({ name: prop.string().default("world") });
    const greeting = useState({ count: 0 });

    function wave() {
      greeting.count++;
    }
  </script>

  <style>
    :host {
      display: block;
    }
  </style>

  <p>Hello, <slot name="@name"></slot>!</p>
  <button onclick="wave()">Waved <slot name="#greeting.count"></slot> times</button>
</custom-element>

<hello-card name="Ana"></hello-card>
```

In this example:

- `defineProps` declares typed attributes. `useState` creates reactive state.
- `<slot name="#greeting.count">` shows a state value. `<slot name="@name">` shows a prop.
- `onclick="wave()"` is a native event handler. It can call functions from the component's script directly.
- The `<style>` is scoped to the component through shadow DOM.

## Why REALM

- REALM uses platform features under their native names: `<slot>` to show content, `on*` attributes for events, `dispatchEvent` to emit them, `ElementInternals` for forms and `:state()` for styling. What you know from plain HTML applies here.
- Markup has no expressions. Attributes and slots hold references such as `#todo.remaining` or `@heading`. Formatting, comparisons and combinations go in the script, usually as getters. The only code in markup is native event handlers, as in plain HTML.
- There is no build step. A page loads one module script from a CDN. Components live inline in the page or in their own `.html` files loaded with `<import-element>`.
- The runtime is about 15 KB gzipped. Updates are batched per microtask and only touch the slots and attributes that read the changed value. Everything a component starts stops when it is removed.

## What REALM is not

- It is not a server framework. It does not render on the server, and pages are not prerendered. See [Modern framework problems](/docs/framework-problems/) for what that means for SEO and first paint.
- It does not compile templates. Plain `let count = 0` does not update the page. Only values from `useState`, `defineProps` and stores do.
- It is not a JavaScript component API. Components are always defined with `<custom-element>`.

## Where to go next

- [Installation](/docs/installation/): two tags from the CDN.
- [Quick start](/docs/quick-start/): a working page in five minutes.
- [Tutorial](/docs/tutorial/): build a reading list app step by step.
- [Component anatomy](/docs/components/): the rules behind the three parts.
- [Components](/components/): REALM UI, a set of about sixty ready-made `ui-*` components.


---

# Installation

Source: http://realm.js.org/docs/installation/

REALM loads from a CDN, so there is nothing to install or build. You need a text editor and a web browser.

## Add REALM from the CDN

Put both tags in the `<head>` of your HTML file:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js"></script>
```

`realm.js` starts REALM when it loads. It defines every `<custom-element>` already in the page, watches for new ones, and registers `<import-element>`.

`realm.css` should load before anything renders. It does three things:

- hides `<custom-element>` definitions and `<import-element>` tags,
- lays out `<is-visible>`, `<is-hidden>` and `<repeat-list>` with `display: contents`,
- hides custom elements until they are defined (`:not(:defined) { visibility: hidden }`), so a page never flashes unstyled component content.

## Add REALM UI

The `@realmorg/ui` package is a set of ready-made `ui-*` components and a theme. Load the theme once per page, after REALM itself. Then import the whole kit with one line:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/theme.css">

<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/ui.html"></import-element>
```

Or import only the components you use. Each one is a file in `components/`:

```html
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/components/button.html"></import-element>
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/components/card.html"></import-element>
```

Each file brings its own dependencies. `sheet.html`, for example, imports `dialog.html` for you. See [Components](/components/).

## A complete page

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>My REALM page</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/theme.css">
  <script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js"></script>
</head>
<body>
  <import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/ui.html"></import-element>

  <ui-button>Hello, REALM</ui-button>
</body>
</html>
```

Save it as `index.html` and open it in your browser.

## Pin a version

`@alpha` is a tag that always points at the newest alpha release. It is the easiest way to try REALM, but jsDelivr caches what a tag points to for up to 12 hours, so a page can keep getting the previous release for a while after a new one comes out.

In production, pin exact versions. An exact version never changes, so a release cannot change your pages, and jsDelivr caches it for a week:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@2.0.0-alpha.2/dist/realm.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/ui@2.0.0-alpha.2/dist/theme.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@2.0.0-alpha.2/dist/realm.js"></script>

<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@2.0.0-alpha.2/dist/ui.html"></import-element>
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/unicons@2.0.0-alpha.1/dist/unicons.html"></import-element>
```

These are the current versions. Each release lists its changes in the package's `CHANGELOG.md`.

## Hosting the files yourself

`<import-element>` fetches component files with `fetch()`, so a file on another domain needs a CORS header that allows your page. jsDelivr sends `Access-Control-Allow-Origin: *` on every file, which is why the tags above work from any site.

To host REALM yourself, install the packages from npm and serve their `dist/` (and, for REALM UI, `components/`) folders from your own domain, or from another domain that sends that header.

```shell
npm install @realmorg/realm@alpha @realmorg/ui@alpha
```

## Sharing JavaScript between components

Shared JavaScript, such as a [store](/docs/stores/), is a plain module file. Import it from a component script with a path the browser can load:

```html
<custom-element name="cart-badge">
  <script type="module">
    import { cart } from "/state/cart.js";
  </script>

  <span><slot name="#cart.items.length">0</slot></span>
</custom-element>
```

To write `import { defineStore } from "@realmorg/realm"` in a module the browser loads directly, add an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) that points at the same file the page loads, so there is one runtime:

```html
<script type="importmap">
  { "imports": { "@realmorg/realm": "https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js" } }
</script>
```

## Serving pages

A page with inline definitions (a `<custom-element>` written directly in the page) works when you open the file straight from disk.

`<import-element>` loads component files with `fetch`, so pages that import your own component files must be served over HTTP rather than opened from `file://`. Any static file server works: your editor's live preview, `python3 -m http.server`, or the static hosting you deploy to.

## Optional: Vite plugin

Load REALM from the CDN in a Vite project too. Component files are plain HTML that REALM fetches at runtime, so serve them as static files from `public/`.

The [Vite plugin](/reference/tooling/vite-plugin/) is an optional dev tool. It pre-assembles components at build time for pages under a strict Content Security Policy, and writes a `custom-elements.json` manifest for editors.

## Next

Continue with the [Quick start](/docs/quick-start/).


---

# References and durations

Source: http://realm.js.org/reference/syntax/

REALM attributes never hold expressions. They hold a **reference** to a value, or a **duration**.

## References

```text
#name.path.to.value
@prop.path
!#name.path
```

| Form | Reads |
| --- | --- |
| `#name` | A top-level name of the component script (`const`, `let`, `var`, `function`, `class` or an import), or a loop variable from `repeat` / `<repeat-list>` |
| `#name.a.b` | A property path on that value. Missing steps give `undefined` instead of throwing |
| `@prop` | A prop declared with [`defineProps`](/reference/script/define-props/). A path may follow: `@user.name` |
| `!#…`, `!@…` | The negation of the value. `!` is the only operator |

The first segment must be a valid JavaScript identifier. Later segments may contain letters, digits, `_`, `$` and `-`, so `#list.0.title` reads the first item.

### Where references are used

| Attribute | Reference |
| --- | --- |
| [`<slot name>`](/reference/elements/value-slots/) | `#…`, `@…`, `!…` |
| [`_name`](/reference/attributes/bindings/) | `#…`, `@…`, `!…` |
| [`<is-visible when>`, `<is-hidden when>`](/reference/elements/is-visible/) | `#…`, `@…`, `!…` |
| [`<repeat-list of>`, `repeat`](/reference/elements/repeat-list/) | `#…`, `@…` |
| [`trigger`](/reference/fetch/trigger/) | `#…`, `@…` among event names |
| [`params`](/reference/fetch/fetch/#params) | `name:#…` pairs |
| [`headers`](/reference/fetch/fetch/#headers) | `#…`, `@…` |
| [`into`](/reference/fetch/into/), [`busy`](/reference/fetch/busy-timeout/) | A **writable** `#name.path` with at least one property: `#todo.items`, not `#todo`, not `@prop`, not negated |

An attribute that needs a reference and gets something else logs `<tag> attribute="…" must be a reference like "#state.path" or "@prop".` and is ignored.

### Resolution order

A `#name` reference is looked up in this order:

1. Loop variables, innermost first.
2. The top-level names of the component whose markup contains the reference.
3. The top-level names of parent components, nearest first (through shadow roots). Each such lookup logs `<child> reads "name" from <parent>.` once, unless the child is a [compound part](/reference/elements/custom-element/#slot).

If nothing defines the name, REALM logs `"#name" is not defined in this component or its parents.` and the value is `undefined`. Handler code uses the same order and finally falls back to `globalThis`. See [Nested components and scope](/docs/scope/).

### Reactivity

A reference updates when the value it reads is reactive: state from [`useState`](/reference/script/use-state/), a [store](/reference/script/define-store/), a prop, a loop variable or a getter on reactive state. A plain top-level `const list = []` can be read, but changes to it are not seen.

## Durations

`debounce`, `throttle`, `poll` and `timeout` take a duration:

| Text | Milliseconds |
| --- | --- |
| `300`, `300ms` | 300 |
| `1.5s` | 1500 |
| `2m` | 120000 |

The pattern is a non-negative number followed by `ms` (default), `s` or `m`. Anything else logs `"…" is not a duration. Use values like "300ms", "2s" or "1m".` and counts as `0`.


---

# Theming

Source: http://realm.js.org/components/theming/

<p class="lead">REALM UI reads its colours, radius, type, spacing and shadows from CSS custom properties in <code>theme.css</code>. Change a token and every component that uses it follows.</p>

## Theme builder

Pick a preset, then change any colour for light and dark mode. The preview uses the real components. The Contrast tab checks each text colour against the surface it sits on, and the CSS tab holds the stylesheet to copy. Your theme is saved in this browser.

<div class="wide-block">
<import-element from="/components/theme-builder.html"></import-element>
<theme-builder></theme-builder>
</div>

## Using a theme

Load your theme after `theme.css`, so your values replace the defaults:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/theme.css">
<link rel="stylesheet" href="/my-theme.css">
```

You only need the tokens you change. To make the corners square and the brand colour blue:

```css
:root {
  --radius: 0;
  --primary: oklch(0.52 0.19 258);
  --ring: oklch(0.6 0.17 255);
}
```

Tokens can be set on any element, not only `:root`. Everything inside it uses the new values:

```css
.billing {
  --primary: oklch(0.5 0.13 152);
}
```

A few tokens are calculated from others where `theme.css` declares them, on `:root`. `--radius-sm` to `--radius-2xl` come from `--radius`, and `--focus-ring` comes from `--ring`. When you change `--radius` or `--ring` on an element instead of `:root`, declare those again on the same element:

```css
.compact {
  --radius: 0.25rem;
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
}
```

## Dark mode

Dark values apply when the system is set to dark. `data-theme="dark"` on `<html>` forces dark mode and `data-theme="light"` forces light mode. A theme sets the dark values in both places:

```css
:root[data-theme="dark"] {
  --primary: oklch(0.7 0.15 250);
}

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --primary: oklch(0.7 0.15 250);
  }
}
```

The theme builder writes both blocks for you.

## Colour tokens

Each surface colour has a `-foreground` partner for the text and icons on it. Keep each pair at a contrast of at least 4.5:1.

| Token | Used for |
| --- | --- |
| `--background`, `--foreground` | The page and its text |
| `--card`, `--card-foreground` | Cards |
| `--popover`, `--popover-foreground` | Popovers, menus, tooltips and dialogs |
| `--primary`, `--primary-foreground` | Default buttons, checked controls, links and the brand colour |
| `--secondary`, `--secondary-foreground` | Secondary buttons and badges |
| `--muted`, `--muted-foreground` | Quiet backgrounds, descriptions and placeholder text |
| `--accent`, `--accent-foreground` | Hovered and highlighted items in lists and menus |
| `--destructive`, `--destructive-foreground` | Delete buttons, errors and invalid fields |
| `--border` | Borders and separators |
| `--input` | Borders of text fields, checkboxes and other controls |
| `--ring` | The focus ring |
| `--chart-1` to `--chart-5` | Chart series |
| `--sidebar`, `--sidebar-*` | The sidebar, with its own foreground, primary, accent, border and ring |

## Other tokens

| Token | Default | Used for |
| --- | --- | --- |
| `--radius` | `0.625rem` | Corner radius. `--radius-xs` to `--radius-2xl` are based on it, and `--radius-full` makes pills |
| `--spacing` | `0.25rem` | The spacing unit. Components use multiples of it, such as `calc(var(--spacing) * 4)` |
| `--font-sans`, `--font-mono` | System fonts | Text and code |
| `--text-xs` to `--text-4xl` | `0.75rem` to `2.25rem` | Font sizes |
| `--font-weight-normal` to `--font-weight-bold` | `400` to `700` | Font weights |
| `--shadow-xs` to `--shadow-lg` | | Shadows |
| `--default-transition-duration` | `150ms` | Hover and state transitions |

To use the tokens in your own styles, read them with `var()`:

```css
.note {
  padding: calc(var(--spacing) * 4);
  border: 1px solid var(--border);
  border-radius: var(--radius-lg);
  background: var(--muted);
  color: var(--muted-foreground);
}
```


---

# Console messages

Source: http://realm.js.org/reference/console/

REALM writes to the console with the prefix `[realm]`. Warnings use `console.warn` and each distinct message is shown once per page. Errors thrown by your code use `console.error`.

## Definitions

| Message | Cause |
| --- | --- |
| `<custom-element name="x"> needs a name that contains a dash, like "todo-app".` | The `name` has no dash. Nothing is defined |
| `<x-a> is defined twice with different sources (a.html and b.html). Keeping the first.` | Two different definitions use the same name. An identical second definition is ignored silently |
| `<x-a> is already defined by another library.` | `customElements` already has that name |
| `<x-a> has more than one <script>. Only the first is used.` | Extra direct `<script>` children |
| `<x-a> is defined in the page, so its <script> needs type="realm". A plain <script> already ran in the page scope.` | An inline definition uses a plain `<script>` |
| `<x-a> has an error in its <script>. The component renders without it.` | The script has a syntax error, or one of its imports failed |
| `<x-a> could not load its script URL: message` | `<script src>` failed to load |
| `Could not load stylesheet URL: message` | A `<link rel="stylesheet">` in a definition failed |
| `<x-a> is nested 1000 deep. Stop its recursion with a condition.` | The component renders itself without a condition that stops it. It is not set up past that depth. See [Recursive components](/docs/control-flow/#recursive-components) |

## Imports

| Message | Cause |
| --- | --- |
| `<import-element> needs a from attribute.` | `from` is missing |
| `<import-element from="…" loading="lazy"> needs a for attribute listing the tags it defines.` | Lazy import without `for`. It loads immediately |
| `Could not import URL (HTTP 404)` | The file failed. `(HTTP …)` is left out for network errors |

## Props

| Message | Cause |
| --- | --- |
| `<x-a> prop "amount" must be at least 0. Using the default.` | An attribute or property value failed a [`prop`](/reference/script/prop/) rule. The text after the prop name describes the rule |
| `<x-a> "name" is not a declared prop.` | Writing a key that `defineProps` did not declare |
| `<x-a> called defineProps more than once.` | Thrown as an error from the script |

## References and markup

| Message | Cause |
| --- | --- |
| `<x-a> attribute="…" must be a reference like "#state.path" or "@prop".` | A reference attribute holds something else |
| `<x-a> "#todo.itmes" is not defined in this component or its parents.` | The first name of a reference is unknown |
| `<x-a> reads "session" from <app-shell>.` | A reference or handler name was found in a parent component. Pass it as a prop to make the dependency explicit |
| `<x-a> repeat has a duplicate key "3".` | Two items share a `key` value. The duplicate gets its own row |
| `"…" is not a duration. Use values like "300ms", "2s" or "1m".` | A bad `debounce`, `throttle`, `poll` or `timeout` |

## Fetch attributes

| Message | Cause |
| --- | --- |
| `<x-a> render-mode="…" is not supported.` | Unknown `render-mode`. `replace` is used |
| `<x-a> render="…" does not match any ref.` | No element has that `ref` |
| `<x-a> "#todo" can't be written. Use a state property like "#todo.items".` | `into` or `busy` is a prop, a negation, or a bare name |
| `<x-a> "#a.b" can't be written because its parent is not an object.` | `#a` is not an object when the response arrives |

## Stores and reactivity

| Message | Cause |
| --- | --- |
| `Stored value for store "cart" is not valid JSON and was ignored.` | Corrupt persisted data. The initial values are kept |
| `Update loop detected: an observer keeps changing state it depends on.` | An error: observers re-ran 100 times in one flush. The queue is cleared |

Errors thrown inside a component script, an observer or a getter are reported with `console.error` and do not stop other components or observers.


---

# Quick start

Source: http://realm.js.org/docs/quick-start/

This page builds a working component in one HTML file, then moves it into its own file. You need a text editor and a web browser. There is nothing to install. REALM loads from a CDN.

## 1. One HTML file

Create `index.html`. The two tags in the `<head>` load REALM from the jsDelivr CDN:

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>My first REALM page</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css">
  <script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js"></script>
</head>
<body>
  <custom-element name="greeting-form">
    <script type="realm">
      const greeting = useState({
        name: "",
        get message() {
          return this.name.trim() ? `Hello, ${this.name.trim()}!` : "";
        },
      });

      function updateName(field) {
        greeting.name = field.value;
      }
    </script>

    <style type="realm">
      :host {
        display: block;
        font-family: system-ui, sans-serif;
      }
    </style>

    <label>
      Your name
      <input _value="#greeting.name" oninput="updateName(this)">
    </label>
    <p><slot name="#greeting.message">Type your name.</slot></p>
  </custom-element>

  <greeting-form></greeting-form>
</body>
</html>
```

Open the file in your browser and type a name. The live version:

```html live
<custom-element name="greeting-form">
  <script type="realm">
    const greeting = useState({
      name: "",
      get message() {
        return this.name.trim() ? `Hello, ${this.name.trim()}!` : "";
      },
    });

    function updateName(field) {
      greeting.name = field.value;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      width: calc(var(--spacing) * 72);
    }
  </style>

  <ui-label for="name">Your name</ui-label>
  <ui-input id="name" _value="#greeting.name" oninput="updateName(this)"></ui-input>
  <p><slot name="#greeting.message">Type your name.</slot></p>
</custom-element>

<greeting-form></greeting-form>
```

How it works:

- `useState` returned a reactive object. Writing `greeting.name` updates everything that reads it.
- `message` is a getter, so it works as a cached derived value.
- `<slot name="#greeting.message">` shows the value as text. While the value is empty, the slot shows its own content, "Type your name.", like a native slot's fallback content.
- `_value="#greeting.name"` binds the input's current value to state. `oninput="updateName(this)"` sends changes back. There is no hidden two-way binding.
- In a page, the script and style use `type="realm"`. The browser ignores those types, so the script does not run in the page's global scope and the style does not leak into the page. REALM picks them up and runs them per component instance.

## 2. Move the component into its own file

In an app, each component usually lives in its own file. Create `greeting-form.html` with the same definition, using a plain `<script>` and `<style>` (the file is never rendered by the browser directly, so no `type` is needed):

```html
<custom-element name="greeting-form">
  <script>
    const greeting = useState({
      name: "",
      get message() {
        return this.name.trim() ? `Hello, ${this.name.trim()}!` : "";
      },
    });

    function updateName(field) {
      greeting.name = field.value;
    }
  </script>

  <style>
    :host {
      display: block;
    }
  </style>

  <label>
    Your name
    <input _value="#greeting.name" oninput="updateName(this)">
  </label>
  <p><slot name="#greeting.message">Type your name.</slot></p>
</custom-element>
```

Then load it from the page:

```html
<import-element from="greeting-form.html"></import-element>
<greeting-form></greeting-form>
```

`<import-element>` fetches the file once, defines every `<custom-element>` in it, and fires `load` or `error`. Because files are loaded with `fetch`, open the page through any static file server rather than from disk, for example your editor's live preview or `python3 -m http.server`. There is still nothing to build.

## 3. Use ready-made components

Add the REALM UI theme and bundle to get buttons, inputs, dialogs and more:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/theme.css">
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/ui.html"></import-element>

<ui-button variant="outline">Click me</ui-button>
```

```html live
<ui-button variant="outline">Click me</ui-button>
```

## Next

- The [Tutorial](/docs/tutorial/) builds a small app with lists, props, persistence and styling.
- [Component anatomy](/docs/components/) explains the rules of the three parts.


---

# Tutorial: a reading list

Source: http://realm.js.org/docs/tutorial/

In this tutorial you build a reading list: add books, mark them as read, filter them, and keep them after a reload. Each step adds one idea. The demos on this page are live, and each step uses a numbered tag name (`reading-list-2`, `reading-list-3`, …) so they can sit on one page. In your own project, call it `reading-list`.

You need a text editor, a browser and one HTML file. Load REALM and REALM UI from the CDN in its `<head>`, as in the [Quick start](/docs/quick-start/):

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/theme.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js"></script>
```

Then import the components at the top of the `<body>`:

```html
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/ui.html"></import-element>
```

## Step 1: markup and style

Start with a component that has no script at all. It is still a custom element with a shadow root and scoped styles.

```html
<custom-element name="reading-list">
  <style type="realm">
    :host {
      display: block;
      width: min(calc(var(--spacing) * 120), 100%);
    }
    form {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    form ui-input {
      flex: 1;
    }
  </style>

  <h2>Reading list</h2>
  <form>
    <ui-input name="title" aria-label="Book title" placeholder="Add a book"></ui-input>
    <ui-button type="submit">Add</ui-button>
  </form>
</custom-element>

<reading-list></reading-list>
```

The style only applies inside the component. `ui-input` and `ui-button` come from [REALM UI](/components/).

## Step 2: state and a list

Add a `<script>`. `useState` returns a reactive object. When a property changes, every slot and binding that reads it updates.

```html live
<custom-element name="reading-list-2">
  <script type="realm">
    const books = useState({ items: [] });
    const draft = useState({ title: "" });

    function add(event) {
      event.preventDefault();
      const title = draft.title.trim();
      if (!title) return;
      books.items.push({ id: crypto.randomUUID(), title, read: false });
      draft.title = "";
    }

    function updateDraft(field) {
      draft.title = field.value;
    }
  </script>

  <style type="realm">
    :host {
      display: block;
      width: min(calc(var(--spacing) * 120), 100%);
    }
    form {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    form ui-input {
      flex: 1;
    }
  </style>

  <form onsubmit="add(event)">
    <ui-input name="title" aria-label="Book title" placeholder="Add a book" _value="#draft.title" oninput="updateDraft(this)"></ui-input>
    <ui-button type="submit">Add</ui-button>
  </form>

  <ul>
    <li repeat="#books.items" as="book" key="id"><slot name="#book.title"></slot></li>
  </ul>
</custom-element>

<reading-list-2></reading-list-2>
```

Four things are new:

- **Handlers call script functions.** `onsubmit="add(event)"` is a native handler attribute, but `add` resolves to the function in the component's script. `event` and `this` work as in plain HTML.
- **Bindings.** `_value="#draft.title"` binds the input's current value to `draft.title`. `oninput` sends typed text back. REALM never writes state for you.
- **Lists.** `repeat="#books.items"` renders one `<li>` per item, with the item available as `book`. Inside `<ul>`, `<ol>`, `<table>` and `<select>`, put `repeat` on the item element itself. Elsewhere you can use the `<repeat-list>` tag.
- **Keys.** `key="id"` lets REALM reuse and move rows when the list changes instead of rebuilding them.

`books.items.push(...)` is enough to update the list. Array methods such as `push`, `splice` and `sort` are tracked.

## Step 3: events per item, derived values and empty states

Each row gets a checkbox and a remove button. Inside a repeated element, the loop variable (`book`) is available in handlers. Getters on the state object are cached derived values, so `summary` recomputes only when the items change.

```html live
<custom-element name="reading-list-3">
  <script type="realm">
    const books = useState({
      items: [
        { id: "dune", title: "Dune", read: true },
        { id: "piranesi", title: "Piranesi", read: false },
      ],
      get unread() {
        return this.items.filter((book) => !book.read).length;
      },
      get summary() {
        return `${this.unread} of ${this.items.length} unread`;
      },
      get isEmpty() {
        return this.items.length === 0;
      },
    });
    const draft = useState({ title: "" });

    function add(event) {
      event.preventDefault();
      const title = draft.title.trim();
      if (!title) return;
      books.items.push({ id: crypto.randomUUID(), title, read: false });
      draft.title = "";
    }

    function updateDraft(field) {
      draft.title = field.value;
    }

    function toggle(book) {
      book.read = !book.read;
    }

    function remove(book) {
      books.items.splice(books.items.indexOf(book), 1);
    }
  </script>

  <style type="realm">
    :host {
      display: block;
      width: min(calc(var(--spacing) * 120), 100%);
    }
    form {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    form ui-input {
      flex: 1;
    }
    ul {
      margin: calc(var(--spacing) * 4) 0 0;
      padding: 0;
      list-style: none;
    }
    li {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 3);
      padding: calc(var(--spacing) * 1) 0;
    }
    li span {
      flex: 1;
    }
    li[data-read] span {
      color: var(--muted-foreground);
      text-decoration: line-through;
    }
    p {
      color: var(--muted-foreground);
      font-size: var(--text-sm);
    }
  </style>

  <form onsubmit="add(event)">
    <ui-input name="title" aria-label="Book title" placeholder="Add a book" _value="#draft.title" oninput="updateDraft(this)"></ui-input>
    <ui-button type="submit">Add</ui-button>
  </form>

  <is-hidden when="#books.isEmpty">
    <ul>
      <li repeat="#books.items" as="book" key="id" _data-read="#book.read">
        <ui-checkbox aria-label="Read" _checked="#book.read" onchange="toggle(book)"></ui-checkbox>
        <span><slot name="#book.title"></slot></span>
        <ui-button variant="ghost" size="sm" onclick="remove(book)">Remove</ui-button>
      </li>
    </ul>
    <p><slot name="#books.summary"></slot></p>
  </is-hidden>

  <is-visible when="#books.isEmpty">
    <p>Nothing here yet. Add the first book above.</p>
  </is-visible>
</custom-element>

<reading-list-3></reading-list-3>
```

- `_data-read="#book.read"` adds `data-read` when the value is `true` and removes it when it is `false`, like a native boolean attribute. The style uses it.
- `<is-hidden when="#books.isEmpty">` and `<is-visible>` mount and unmount their content. Unmounted content has no running bindings or listeners.
- Markup only holds references, never expressions. "How many are unread" is a getter in the script, not a calculation in the markup.

## Step 4: filters, props and reactive CSS

Filters are a lookup table, so adding one is a one-line change. The heading becomes a prop, declared with `defineProps`, so each instance can set it as an attribute. The empty state is styled with a reactive CSS state.

```html live
<custom-element name="reading-list-4">
  <script type="realm">
    const props = defineProps({ heading: prop.string().default("Reading list") });

    const FILTERS = {
      all: { label: "All", keep: () => true },
      unread: { label: "Unread", keep: (book) => !book.read },
      read: { label: "Read", keep: (book) => book.read },
    };

    const books = useState({
      items: [
        { id: "dune", title: "Dune", read: true },
        { id: "piranesi", title: "Piranesi", read: false },
        { id: "circe", title: "Circe", read: false },
      ],
      filter: "all",
      get visible() {
        return this.items.filter(FILTERS[this.filter].keep);
      },
      get filters() {
        return Object.entries(FILTERS).map(([id, filter]) => ({
          id,
          label: filter.label,
          pressed: id === this.filter,
          variant: id === this.filter ? "secondary" : "ghost",
        }));
      },
      get summary() {
        return `${this.items.filter(FILTERS.unread.keep).length} of ${this.items.length} unread`;
      },
      get isEmpty() {
        return this.items.length === 0;
      },
    });
    const draft = useState({ title: "" });

    function add(event) {
      event.preventDefault();
      const title = draft.title.trim();
      if (!title) return;
      books.items.push({ id: crypto.randomUUID(), title, read: false });
      draft.title = "";
    }

    function updateDraft(field) {
      draft.title = field.value;
    }

    function toggle(book) {
      book.read = !book.read;
    }

    function remove(book) {
      books.items.splice(books.items.indexOf(book), 1);
    }

    function show(filter) {
      books.filter = filter.id;
    }
  </script>

  <style type="realm">
    :host {
      display: block;
      width: min(calc(var(--spacing) * 120), 100%);
    }
    h2 {
      margin: 0 0 calc(var(--spacing) * 4);
      font-size: var(--text-xl);
    }
    form,
    footer {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    form ui-input {
      flex: 1;
    }
    ul {
      margin: calc(var(--spacing) * 4) 0;
      padding: 0;
      list-style: none;
      border: 1px solid var(--border);
      border-radius: var(--radius-lg);
    }
    li {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 3);
      padding: calc(var(--spacing) * 2) calc(var(--spacing) * 3);
      border-bottom: 1px solid var(--border);
    }
    li:last-child {
      border-bottom: 0;
    }
    li span {
      flex: 1;
    }
    li[data-read] span {
      color: var(--muted-foreground);
      text-decoration: line-through;
    }
    footer {
      align-items: center;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
    footer span {
      flex: 1;
    }
    :host(:state(state-books-isEmpty)) ul,
    :host(:state(state-books-isEmpty)) footer {
      display: none;
    }
  </style>

  <h2><slot name="@heading"></slot></h2>

  <form onsubmit="add(event)">
    <ui-input name="title" aria-label="Book title" placeholder="Add a book" _value="#draft.title" oninput="updateDraft(this)"></ui-input>
    <ui-button type="submit">Add</ui-button>
  </form>

  <ul>
    <li repeat="#books.visible" as="book" key="id" _data-read="#book.read">
      <ui-checkbox aria-label="Read" _checked="#book.read" onchange="toggle(book)"></ui-checkbox>
      <span><slot name="#book.title"></slot></span>
      <ui-button variant="ghost" size="sm" onclick="remove(book)">Remove</ui-button>
    </li>
  </ul>

  <footer>
    <span><slot name="#books.summary"></slot></span>
    <repeat-list of="#books.filters" as="filter" key="id">
      <ui-button size="sm" _variant="#filter.variant" _aria-pressed="#filter.pressed" onclick="show(filter)"><slot name="#filter.label"></slot></ui-button>
    </repeat-list>
  </footer>
</custom-element>

<reading-list-4 heading="Books for the summer"></reading-list-4>
```

- `defineProps` declares typed attributes. `<slot name="@heading">` shows a prop. `@` means "prop", `#` means "script value".
- `_variant="#filter.variant"` passes a value to another component's prop. `_aria-pressed` receives `"true"` or `"false"`, as ARIA expects.
- `:host(:state(state-books-isEmpty))` matches while `books.isEmpty` is truthy. REALM sets these custom states for every `:state(state-…)` and `:state(attr-…)` selector it finds in the component's styles. See [Styling](/docs/styling/).
- `<repeat-list>` repeats any content where a list element is not needed.

## Step 5: keep the list after a reload

Swap `useState` for `defineStore` to share the list between every instance and save it to `localStorage`. Values come back with their types, so booleans stay booleans.

```html live
<custom-element name="reading-list-5">
  <script type="realm">
    const books = defineStore(
      "tutorial-reading-list",
      {
        items: [],
        get isEmpty() {
          return this.items.length === 0;
        },
      },
      { persist: "local" },
    );
    const draft = useState({ title: "" });

    function add(event) {
      event.preventDefault();
      const title = draft.title.trim();
      if (!title) return;
      books.items.push({ id: crypto.randomUUID(), title, read: false });
      draft.title = "";
    }

    function updateDraft(field) {
      draft.title = field.value;
    }

    function toggle(book) {
      book.read = !book.read;
    }

    function remove(book) {
      books.items.splice(books.items.indexOf(book), 1);
    }
  </script>

  <style type="realm">
    :host {
      display: block;
      width: min(calc(var(--spacing) * 120), 100%);
    }
    form {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    form ui-input {
      flex: 1;
    }
    ul {
      margin: calc(var(--spacing) * 4) 0 0;
      padding: 0;
      list-style: none;
    }
    li {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 3);
      padding: calc(var(--spacing) * 1) 0;
    }
    li span {
      flex: 1;
    }
    li[data-read] span {
      color: var(--muted-foreground);
      text-decoration: line-through;
    }
    p {
      color: var(--muted-foreground);
      font-size: var(--text-sm);
    }
  </style>

  <form onsubmit="add(event)">
    <ui-input name="title" aria-label="Book title" placeholder="Add a book, then reload the page" _value="#draft.title" oninput="updateDraft(this)"></ui-input>
    <ui-button type="submit">Add</ui-button>
  </form>

  <ul>
    <li repeat="#books.items" as="book" key="id" _data-read="#book.read">
      <ui-checkbox aria-label="Read" _checked="#book.read" onchange="toggle(book)"></ui-checkbox>
      <span><slot name="#book.title"></slot></span>
      <ui-button variant="ghost" size="sm" onclick="remove(book)">Remove</ui-button>
    </li>
  </ul>

  <is-visible when="#books.isEmpty">
    <p>Your saved list is empty.</p>
  </is-visible>
</custom-element>

<reading-list-5></reading-list-5>
```

Add a book and reload the page. It is still there. In a larger app, define the store in its own JavaScript module and import it from every component that needs it. See [Stores](/docs/stores/).

## Step 6: move it into a file

Put the finished definition in `reading-list.html`, switch `type="realm"` back to a plain `<script>` and `<style>`, and load it. Open the page through any static file server (your editor's live preview works), because `<import-element>` loads files with `fetch`:

```html
<import-element from="/components/reading-list.html"></import-element>

<reading-list heading="Books for the summer"></reading-list>
```

## What you used

| Idea | Where to read more |
| --- | --- |
| `useState`, getters, `defineStore` | [State and reactivity](/docs/state/), [Stores](/docs/stores/) |
| `<slot name="#…">`, `_attr="#…"` | [Values and bindings](/docs/bindings/) |
| `onsubmit="add(event)"`, loop variables in handlers | [Events](/docs/events/) |
| `<is-visible>`, `<is-hidden>` | [Control flow](/docs/control-flow/) |
| `repeat`, `<repeat-list>`, `key` | [Lists and keys](/docs/lists/) |
| `defineProps` | [Props](/docs/props/) |
| `:state(state-…)` | [Styling](/docs/styling/) |
| `<import-element>` | [Importing components](/docs/importing/) |


---

# `<custom-element>`

Source: http://realm.js.org/reference/elements/custom-element/

Defines a component. The definition holds an optional `<script>`, any number of `<style>` and `<link rel="stylesheet">` elements, and the markup every instance renders in its shadow root. There is no `<template>` wrapper and no JavaScript definition API.

```html
<custom-element name="tag-name"
  [form-associated] [role="…"] [delegates-focus] [slot="…"]>
  <script type="realm">/* runs once per element */</script>
  <style type="realm">/* scoped to the component */</style>
  <!-- markup -->
</custom-element>
```

`type="realm"` is for definitions written in a page. In a file loaded with [`<import-element>`](/reference/elements/import-element/), use a plain `<script>` and `<style>`. See [The script](#the-script).

```html live
<custom-element name="click-counter">
  <script type="realm">
    const props = defineProps({ step: prop.number().int().default(1) });
    const count = useState({ value: 0 });

    function add() {
      count.value += props.step;
    }
  </script>

  <style type="realm">
    :host {
      display: inline-flex;
      align-items: center;
      gap: calc(var(--spacing) * 3);
    }
  </style>

  <ui-button onclick="add()">Add</ui-button>
  <output>Count: <slot name="#count.value"></slot></output>
</custom-element>

<click-counter step="2"></click-counter>
```

## Attributes

| Attribute | Type | Default | Meaning |
| --- | --- | --- | --- |
| `name` | tag name containing `-` | required | The element name. Without a dash REALM warns and defines nothing |
| `form-associated` | boolean | absent | Makes the element a form field (`static formAssociated = true`). See [Forms](/docs/forms/) |
| `role` | ARIA role | none | Default role, set as `internals.role`. Page authors can still override it with a `role` attribute |
| `delegates-focus` | boolean | absent | Attaches the shadow root with `delegatesFocus: true`, so focusing the host focuses the first focusable element inside |
| `slot` | slot name | none | Makes the component a compound part. See [slot](#slot) |

### form-associated

A form-associated component:

- takes part in form submission, reset, validation, `<fieldset disabled>` and `<label>` like a native field,
- sets its form value from the `value` prop (and from `checked` when it declares one, sending `value` or `"on"` while checked),
- re-reads its attributes on form reset and restores `value` or `checked` on back/forward navigation,
- delegates to an inner `<input>`, `<select>` or `<textarea>` marked [`ref="control"`](/reference/attributes/ref/#ref-control),
- reports `props.disabled` as `true` while a surrounding fieldset is disabled, and starts disabled when created inside one,
- can use [`onFormReset`](/reference/script/on-form-reset/), [`onFormDisabled`](/reference/script/on-form-disabled/) and [`onFormStateRestore`](/reference/script/on-form-state-restore/).

### slot

With `slot="title"` on the definition, every instance gets `slot="title"` unless it sets its own `slot`, so it lands in the parent's `title` slot. A part like this can call its parent's functions and show its parent's state without a script, and those parent lookups do not log the usual `reads "name" from <parent>` message.

```html
<custom-element name="card-title" slot="title">
  <h3><slot></slot></h3>
</custom-element>
```

## Children

| Child | Meaning |
| --- | --- |
| First `<script>` | The component script. Extra scripts log a warning and are ignored |
| `<style>` | Adopted into every instance's shadow root. Scoped to the component |
| `<link rel="stylesheet" href>` | Fetched once (relative to the file that holds the definition) and adopted like `<style>`. A failed load warns |
| Anything else | Markup, cloned into each instance's open shadow root |

Styles are scanned for [`var(--attr-*)`, `var(--state-*)`](/reference/css/variables/) and [`:state(…)`](/reference/css/states/) so those stay reactive.

## The script

The script runs **once per element**, when it is first connected. Its top-level `const`, `let`, `var`, `function` and `class` names and its imports can be referenced from markup (`#name.path`) and called from handlers. The [script helpers](/reference/script/) are in scope without importing.

| Script | Where | Behaviour |
| --- | --- | --- |
| `<script type="realm">` | Definitions written in a page | The browser ignores the type, so the code only runs as the component script. A plain `<script>` in a page definition has already run in the page scope, and REALM warns |
| `<script>` | Files loaded with [`<import-element>`](/reference/elements/import-element/) | Files are parsed, not executed, so a plain script is safe |
| `<script type="module">` | Either | Use it when the script has `import` statements, for readability. REALM treats any script with leading `import` statements as a module |
| `<script src="setup.js">` | Either | Loads a **pre-assembled setup module** produced by the [Vite plugin](/reference/tooling/vite-plugin/) or [`compileDefinition`](/reference/javascript/compiler/). It is not a way to load a plain script file |

`import` statements must come first. Relative specifiers (`./store.js`) are resolved against the file that holds the definition. A script with a syntax error, or whose import fails, logs a warning and the component renders without it. An error thrown while the script runs is logged with `console.error`, and the markup still renders.

Use `<style type="realm">` in page definitions too, so the browser does not apply the styles to the page before REALM reads them.

## Instances

- Each instance gets an open shadow root with the definition's stylesheets and markup.
- Moving an element (removing and re-inserting it in the same task) keeps its state. Removing it tears it down: observers stop, listeners and requests abort, [`onDisconnected`](/reference/script/on-disconnected/) hooks run.
- The `hidden` attribute always hides a component, whatever `display` its styles set.
- REALM elements written inside a page definition are not mounted while they are part of the definition.
- Defining the same name with the same source twice is ignored. A different source logs a warning and the first is kept. A name another library already registered logs a warning.

## Where definitions go

Inline in a page (REALM defines them on start and when they are added later) or in an HTML file loaded with [`<import-element>`](/reference/elements/import-element/). `realm.css` hides definitions with `display: none`.

## Related

- [Component anatomy](/docs/components/)
- [Component script](/reference/script/)
- [Nested components and scope](/docs/scope/)


---

# Component anatomy

Source: http://realm.js.org/docs/components/

A component is defined by one `<custom-element>` tag. Its `name` must contain a dash, like every custom element name. Inside it there are three kinds of children, in any order:

| Part | What it holds | Rules |
| --- | --- | --- |
| `<script>` | The component's logic in plain JavaScript | At most one. It runs once per element instance |
| `<style>` and `<link rel="stylesheet">` | The component's CSS | Adopted into the component's shadow root, so it only applies inside |
| Everything else | Markup | Value slots, `_` bindings, native event handlers, fetch attributes and the REALM tags |

There is no `<template>` wrapper and no JavaScript definition API.

```html
<custom-element name="user-badge">
  <script>
    const props = defineProps({ name: prop.string().default("Guest") });
    const badge = useState({
      get initials() {
        return props.name.split(" ").map((part) => part[0]).join("");
      },
    });
  </script>

  <style>
    :host {
      display: inline-flex;
      gap: calc(var(--spacing) * 2);
      align-items: center;
    }
  </style>

  <ui-avatar><ui-avatar-fallback><slot name="#badge.initials"></slot></ui-avatar-fallback></ui-avatar>
  <span><slot name="@name"></slot></span>
</custom-element>
```

## Attributes on the definition

| Attribute | Effect |
| --- | --- |
| `name` | The tag name. Required, must contain a dash |
| `form-associated` | Makes the element a form field through `ElementInternals`. See [Forms](/docs/forms/) |
| `role` | Default ARIA role for every instance, set through `ElementInternals.role` |
| `delegates-focus` | Creates the shadow root with `delegatesFocus: true`, so focusing the host focuses the first focusable element inside |

## Where definitions live

**In their own file** (recommended). A file such as `user-badge.html` can hold one or many `<custom-element>` definitions and is loaded with `<import-element from="user-badge.html">`. The file is parsed off-page with `DOMParser`, so nothing in it runs or renders until REALM assembles it. Use a plain `<script>` and `<style>`, or `<script type="module">` when the script uses `import`.

**Inline in the page**, for prototypes and demos. Write the definition anywhere in the page and give its script and style `type="realm"`:

```html
<custom-element name="hello-there">
  <script type="realm">
    const hello = useState({ who: "there" });
  </script>
  <style type="realm">
    p { font-weight: var(--font-weight-semibold); }
  </style>
  <p>Hello, <slot name="#hello.who"></slot></p>
</custom-element>

<hello-there></hello-there>
```

The browser ignores scripts and styles with an unknown `type`, so the script does not run in the page scope and the style does not apply to the page. A plain `<script>` in an inline definition has already run as page JavaScript by the time REALM sees it, so REALM warns about it. REALM removes inline definitions from the page once it has read them, including ones added to the page later.

So `type="realm"` belongs only on definitions written in a page. The live demos on this site define their components in the page so the preview runs in place, but their source tabs show each definition the recommended way: in its own file with a plain `<script>` and `<style>`, loaded from `index.html` with `<import-element>`.

## How it works without a compiler

You never write this yourself, but it explains several rules.

1. **Read.** REALM separates the script, styles and markup, and collects every native event handler in the markup.
2. **Assemble.** It builds one script for the component type. Your script becomes the body of a setup function, unchanged, and each event handler from the markup is placed inside that same function. That is why `onclick="save()"` can call `save` directly.
3. **Run.** The script is inserted as a normal `<script>` element (a module script when your script has `import` statements). If the page has a script with a CSP `nonce`, REALM copies it. REALM never uses `eval`, `new Function` or `blob:` URLs.
4. **Define.** REALM registers a native custom element. Each time one connects, it creates a shadow root, adopts the shared stylesheets, runs setup for that instance, then clones the markup and connects every slot, binding and handler.

Rules that follow:

| Rule | Why |
| --- | --- |
| The script runs once per instance | It is the body of the setup function. Code shared between instances goes in a module you import |
| `import` statements go at the top of the script | They are moved above the wrapper. Relative paths resolve against the component file |
| Only `useState`, `defineProps` and store values update the page | A plain `let count = 0; count++` changes a variable that nothing can observe |
| Markup that arrives later is never scanned | HTML from requests or `html` slots is data. It is sanitised and never gets handlers or bindings. See [Security](/docs/security/) |
| Top-level names are what markup can reference | `#todo.items` reads the top-level `todo` from the script. Names declared inside functions or blocks are not visible to markup |

## Helpers available in the script

These names are in scope in every component script without importing anything:

| Helper | Purpose |
| --- | --- |
| `defineProps(schema)` | Declare typed attributes. See [Props](/docs/props/) |
| `prop` | The prop type builder used with `defineProps` |
| `useState(object)` | Reactive state. See [State and reactivity](/docs/state/) |
| `observe(fn)` | Run code now and again whenever what it read changes |
| `tick()` | Wait until pending updates are applied to the DOM |
| `defineStore(name, initial, options)` | App-wide state, optionally persisted. See [Stores](/docs/stores/) |
| `defineMethods(object)` | Add public methods and getters to the element |
| `dispatch(type, detail, options)` | Emit a bubbling, composed, cancelable `CustomEvent` from the host |
| `listen(type, handler, target)` | `addEventListener` that stops when the element is removed |
| `attrs` | Reactive read and write access to any host attribute |
| `useChildren(selector, attributes)` | A reactive list of the host's light DOM children that match a selector |
| `onConnected`, `onDisconnected` | Lifecycle hooks. See [Lifecycle](/docs/lifecycle/) |
| `onFormReset`, `onFormDisabled`, `onFormStateRestore` | Form lifecycle hooks |
| `lookup(name)` | Find a name in parent components, then globals |
| `host` | The element itself |
| `refs` | Elements marked with `ref="name"` in the markup |
| `signal` | An `AbortSignal` that aborts when the element is removed |
| `internals` | The element's `ElementInternals` |

Write scripts in this order: `defineProps`, then `useState`, then functions, then `defineMethods`, `listen`, lifecycle hooks and `observe` last. Keep them short: logic that several components need belongs in a shared module or a store.

The [API reference](/reference/script/) lists every signature.

## Errors

- A syntax error in a script is reported once and the component renders its markup without the script.
- An error thrown while the script runs is reported, and the markup still renders.
- Defining the same source twice does nothing. A different definition for a name that already exists keeps the first one and warns, naming both files. A name already registered by another library is left alone, with a warning.
- More than one `<script>` in a definition: only the first is used, with a warning.

REALM warnings start with `[realm]` in the console and are shown once each.


---

# `<import-element>`

Source: http://realm.js.org/reference/elements/import-element/

Loads an HTML file and defines every `<custom-element>` in it. Works in a page and inside component markup. `realm.css` hides it.

```html
<import-element from="URL" [loading="lazy" for="tag-a tag-b"]></import-element>
```

```html
<import-element from="components/todo-app.html"></import-element>
<todo-app></todo-app>
```

## Attributes

| Attribute | Type | Default | Meaning |
| --- | --- | --- | --- |
| `from` | URL | required | File to load, resolved against the element's base URL (the page). Without it REALM warns and does nothing |
| `loading` | `lazy` | eager | With `lazy`, wait until one of the tags in `for` appears in the page or in a component's markup |
| `for` | space-separated tag names | none | The tags the file defines. Required for `loading="lazy"`. Without it the import starts at once with a warning |

The attributes are read once, when the element first connects. Reconnecting does not import again.

## Events

Fired on the `<import-element>`. They do not bubble. See [Import events](/reference/events/import-events/).

| Event | `detail` | When |
| --- | --- | --- |
| `load` | `{ url: string }` | Every definition in the file is defined |
| `error` | `{ url: string, status: number }` | The file could not be loaded. `status` is `0` for network errors |

Neither fires if the element was removed before the file arrived. Handle them with `onload` / `onerror` attributes or `addEventListener`.

## Behaviour

- Each URL is fetched once per page. Several `<import-element>` tags, or [`importDefinitions`](/reference/javascript/import-definitions/) calls, for the same file share one request.
- At most six imports per origin load at once. The rest wait in order.
- The file is parsed as an HTML document, never executed. Only its `<custom-element>` elements are used. Other content is ignored.
- Relative URLs inside definitions (`<link rel="stylesheet">`, `import` in scripts) resolve against the imported file, not the page.
- Files must be served over HTTP. `file://` pages cannot fetch them.

## Example: lazy loading and the load event

```html live
<import-element from="/examples/todo/todo-app.html" loading="lazy" for="todo-app" onload="document.getElementById('lazy-status').value = 'Loaded ' + event.detail.url"></import-element>

<ui-button onclick="document.getElementById('lazy-target').replaceChildren(document.createElement('todo-app'))">Show a todo-app</ui-button>
<p><output id="lazy-status">todo-app.html is not loaded yet.</output></p>
<div id="lazy-target"></div>
```

`todo-app.html` is fetched only when the button adds a `<todo-app>` to the page. `onload` is a native handler attribute, so it works on a plain page.

## Related

- [Importing components](/docs/importing/)
- [Installation](/docs/installation/)


---

# Props

Source: http://realm.js.org/docs/props/

Props are a component's public attributes. Declare them with `defineProps` and the `prop` builder, which converts attribute text into typed values, validates them and supplies defaults.

```js
const props = defineProps({
  heading: prop.string().default("Todos"),
  count: prop.number().int().min(0).default(0),
  variant: prop.enum(["primary", "ghost", "danger"]).default("primary"),
  disabled: prop.boolean(),
  tags: prop.array(prop.string()).default([]),
  user: prop.object({ name: prop.string(), email: prop.string().email() }).optional(),
  href: prop.string().url().required(),
  size: prop.number().attribute("data-size").reflect(),
});
```

`defineProps` returns a reactive object. Read it in the script (`props.count`) and in markup with `@` references:

```html
<h2><slot name="@heading"></slot></h2>
<button _disabled="@disabled">Save</button>
```

```html live
<custom-element name="price-tag">
  <script type="realm">
    const props = defineProps({
      amount: prop.number().min(0).default(0),
      currency: prop.enum(["USD", "EUR", "JPY"]).default("USD"),
      sale: prop.boolean(),
    });

    const price = useState({
      get label() {
        return new Intl.NumberFormat("en", { style: "currency", currency: props.currency }).format(props.amount);
      },
    });
  </script>

  <style type="realm">
    :host {
      display: inline-flex;
      gap: calc(var(--spacing) * 2);
      align-items: center;
      font-variant-numeric: tabular-nums;
    }
  </style>

  <strong><slot name="#price.label"></slot></strong>
  <ui-badge variant="destructive" _hidden="!@sale">Sale</ui-badge>
</custom-element>

<price-tag amount="19.5"></price-tag>
<price-tag amount="12" currency="EUR" sale></price-tag>
<price-tag amount="-3" currency="JPY"></price-tag>
```

The third tag has an invalid amount. REALM logs a warning naming the component, the prop and the rule, then uses the default (`0`). Invalid values never crash a component.

## Types

| Builder | Attribute text is converted with | Rules |
| --- | --- | --- |
| `prop.string()` | As-is | `.min(n)`, `.max(n)` (length), `.pattern(regex)`, `.email()`, `.url()` |
| `prop.number()` | `Number(text)`. Empty text is invalid | `.int()`, `.min(n)`, `.max(n)` |
| `prop.boolean()` | Native rule: present is `true`, absent is `false` | |
| `prop.enum([...])` | Must be one of the listed strings | |
| `prop.date()` | `new Date(text)`, usually ISO text | Must be a valid date |
| `prop.array(item?)` | `JSON.parse(text)` | Each item is checked against `item` |
| `prop.object(shape?)` | `JSON.parse(text)` | Each key in `shape` is checked |

Arrays and objects are usually passed as properties, not written by hand as JSON. See [Passing objects](#passing-objects).

## Modifiers

| Modifier | Meaning |
| --- | --- |
| `.default(value)` | Used when the attribute is missing or its value is invalid. Object and array defaults are cloned per instance |
| `.required()` | A missing value is reported with a warning |
| `.optional()` | Allows `undefined` |
| `.reflect()` | Setting the property also writes the attribute (`false`, `null` and `undefined` remove it, `true` writes an empty attribute) |
| `.attribute("name")` | Use a different attribute name. By default `maxItems` maps to `max-items` |

Without a default, a missing prop is `undefined`, except booleans, which are `false`.

## Attributes and properties

Each prop is both an attribute and a property on the element, like native elements:

```js
const tag = document.querySelector("price-tag");
tag.amount = 25; // property: validated, not written to the attribute
tag.setAttribute("amount", "30"); // attribute: parsed, then validated
```

- Attribute changes are picked up automatically (through a `MutationObserver`, so they apply in the next microtask).
- Properties set on an element before its definition loads are kept and applied on upgrade.
- A prop with `.reflect()` writes the attribute back when the property changes, which makes it usable from CSS selectors such as `:host([open])`.

## Writing props from inside

`props` is read-mostly. Writing a declared prop from the component goes through the same validation as a property write, and reflects if the prop reflects:

```js
const props = defineProps({ open: prop.boolean().reflect() });

function toggle() {
  props.open = !props.open;
}
```

Writing a name that is not declared logs a warning and does nothing. Use `useState` for internal values.

## Passing objects

A `_` binding to another REALM component passes objects and arrays as properties, so they arrive intact instead of being turned into text:

```html
<user-card _user="#session.user" _compact="@compact"></user-card>
```

```js
// inside user-card
const props = defineProps({
  user: prop.object({ name: prop.string(), email: prop.string().email() }),
  compact: prop.boolean(),
});
```

Strings, numbers and booleans are written as attributes, which the child parses with its own prop types.

## Props in CSS

Every prop can be read in the component's styles as `var(--attr-name)` and matched with `:state(attr-name)` or `:state(attr-name-is-value)`:

```css
:host(:state(attr-variant-is-danger)) button {
  background: var(--destructive);
}
```

See [Styling](/docs/styling/).

## One call per component

`defineProps` may be called once per script. A second call is reported as an error. Put every prop in one schema.


---

# `<repeat-list>`

Source: http://realm.js.org/reference/elements/repeat-list/

Repeats its content once per item of an array. Laid out with `display: contents`, so it adds no box. Used in component markup.

```html
<repeat-list of="#ref" [as="item"] [index="i"] [key="id"]>
  …content per item…
</repeat-list>
```

Inside `<ul>`, `<ol>`, `<table>`, `<tbody>`, `<tr>` and `<select>`, the HTML parser does not allow unknown elements. Use the [`repeat` attribute](/reference/attributes/repeat/) on the item element there.

## Attributes

| Attribute | Type | Default | Meaning |
| --- | --- | --- | --- |
| `of` | [reference](/reference/syntax/) to an array | required | The list. Anything that is not an array renders nothing |
| `as` | name | `item` | Variable name for the current item |
| `index` | name | none | Variable name for the current position (0-based). Only defined when set |
| `key` | property name | position | Property of each item that identifies it between updates |

## Inside each copy

- `#item.title`, `#i` work in value slots, `_` bindings, `<is-visible>` and nested lists.
- `item` and `i` are variables in handler code: `onclick="remove(item)"`.
- Every other name still resolves to the component script, so `#todo.filter` works inside the loop.
- Loops nest. An inner loop can read the outer loop's variables.

## Keys

With `key`, items are matched by that property when the array changes:

| Change | Result |
| --- | --- |
| Item still present | Its nodes are kept and updated in place. Focus, typed text and transitions survive |
| Item moved | Its nodes are moved, not re-created |
| Item removed | Its nodes are removed and its listeners, observers and requests stop |
| New item | New nodes are created |

Without `key`, items are matched by position. A duplicate key logs `repeat has a duplicate key "…"` and the duplicate gets its own row.

## Example

```html live
<custom-element name="fruit-list">
  <script type="realm">
    const basket = useState({
      next: 4,
      items: [
        { id: 1, name: "Apple" },
        { id: 2, name: "Banana" },
        { id: 3, name: "Cherry" },
      ],
    });

    function add() {
      basket.items.unshift({ id: basket.next, name: `Fruit ${basket.next}` });
      basket.next++;
    }

    function remove(fruit) {
      basket.items = basket.items.filter((item) => item.id !== fruit.id);
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      justify-items: start;
    }
    p {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 2);
      margin: 0;
    }
  </style>

  <ui-button onclick="add()">Add to top</ui-button>
  <repeat-list of="#basket.items" as="fruit" index="i" key="id">
    <p>
      <slot name="#i"></slot>.
      <slot name="#fruit.name"></slot>
      <ui-button variant="ghost" size="sm" onclick="remove(fruit)">Remove</ui-button>
    </p>
  </repeat-list>
</custom-element>

<fruit-list></fruit-list>
```

## Related

- [Lists and keys](/docs/lists/)
- [`repeat` attribute](/reference/attributes/repeat/)


---

# State and reactivity

Source: http://realm.js.org/docs/state/

REALM's reactivity has three pieces: `useState` for state, getters for derived values, and `observe` for side effects. There are no dependency lists. REALM records what each binding, getter and observer reads, and re-runs only those when the values change.

## useState

`useState(object)` returns a reactive proxy of the object. Reading a property inside a slot, binding, getter or observer subscribes to it. Writing it notifies them.

```js
const todo = useState({
  items: [],
  draft: "",
  filter: "all",
});

todo.draft = "Buy milk"; // updates every slot and binding that reads todo.draft
todo.items.push({ id: 1, text: "Buy milk", done: false });
todo.items[0].done = true; // nested objects are reactive too
delete todo.filter; // added and deleted keys are tracked
```

- Nested plain objects and arrays become reactive when you read them.
- Array methods that change the array (`push`, `pop`, `shift`, `unshift`, `splice`, `sort`, `reverse`, `fill`, `copyWithin`), index writes and `length` writes all notify.
- `includes`, `indexOf` and `lastIndexOf` find an item from either the reactive item or the original object.
- Writing the same value again does nothing.
- Only plain objects and arrays are made reactive. `Map`, `Set`, `Date` and class instances are stored as they are. Replace them to trigger an update.
- `useState` called twice with the same object returns the same proxy.

Plain variables are not reactive. `let count = 0` followed by `count++` changes a variable that nothing observes, so the page does not update. Put anything the markup shows into `useState`.

## Getters are derived values

A getter on a state object is a cached derived value. It computes on first read, then only again after something it read has changed.

```js
const cart = useState({
  items: [],
  get total() {
    return this.items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  },
  get totalLabel() {
    return `$${this.total.toFixed(2)}`;
  },
  get isEmpty() {
    return this.items.length === 0;
  },
});
```

Markup only holds references, so getters are where comparisons and formatting go:

```html
<p _hidden="#cart.isEmpty">Total: <slot name="#cart.totalLabel"></slot></p>
```

Getters can read props, other state objects and stores. When two getters share an input, observers still run once and never see a stale value. A setter on a state object runs with the proxy as `this`, so its writes are reactive. A getter that throws reports the error and recovers on the next change.

## Updates are batched

Changes are collected and applied once per microtask. Five writes in a row cause one update of each affected binding:

```js
function reset() {
  form.name = "";
  form.email = "";
  form.message = "";
  form.sent = false;
}
```

## observe

`observe(fn)` runs `fn` now, and again whenever anything it read changes. It returns a function that stops it. In a component script, observers stop automatically when the element is removed.

If `fn` returns a function, that function runs before the next run and when the observer stops. Use it to undo what the run started:

```html live
<custom-element name="stop-watch">
  <script type="realm">
    const props = defineProps({ interval: prop.number().min(10).default(100) });

    const watch = useState({
      elapsed: 0,
      running: false,
      get seconds() {
        return (this.elapsed * props.interval / 1000).toFixed(1);
      },
      get action() {
        return this.running ? "Stop" : "Start";
      },
    });

    function toggle() {
      watch.running = !watch.running;
    }

    function reset() {
      watch.elapsed = 0;
    }

    observe(() => {
      if (!watch.running) return;
      const id = setInterval(() => watch.elapsed++, props.interval);
      return () => clearInterval(id);
    });
  </script>

  <style type="realm">
    :host {
      display: inline-flex;
      gap: calc(var(--spacing) * 2);
      align-items: center;
      font-variant-numeric: tabular-nums;
    }
    output {
      min-width: calc(var(--spacing) * 16);
      font-size: var(--text-2xl);
      font-weight: var(--font-weight-semibold);
    }
  </style>

  <output><slot name="#watch.seconds"></slot>s</output>
  <ui-button onclick="toggle()"><slot name="#watch.action"></slot></ui-button>
  <ui-button variant="outline" onclick="reset()">Reset</ui-button>
</custom-element>

<stop-watch></stop-watch>
```

The observer reads `watch.running` and `props.interval`. When either changes, the previous interval is cleared by the returned function and a new run decides whether to start another. Removing the element stops it.

Things to know:

- An observer that throws is reported and does not stop other observers.
- An observer that keeps changing a value it also reads is stopped after 100 rounds, with an "Update loop detected" error.
- Observers inside observers keep their own dependencies.
- Put observers last in the script, after the functions they use.

### Why not an effect with a dependency array

`observe` has no list to keep in sync with the code, and it does not run after every render, because there are no renders. It runs once, then only when something it read has changed.

## Reading without subscribing

`untrack(fn)` runs `fn` without subscribing the current observer to what it reads. `toRaw(proxy)` returns the original object behind a reactive proxy, which is useful before handing data to `structuredClone` or `JSON.stringify` in hot paths. Both are exported from `@realmorg/realm`:

```js
import { toRaw, untrack } from "@realmorg/realm";
```

## tick

Updates are applied in a microtask, so right after a state change the DOM still shows the old value. `await tick()` waits until pending updates have been applied:

```js
async function edit(item) {
  item.editing = true;
  await tick();
  refs.editor.focus();
}
```

`flush()`, exported from the package, applies pending updates synchronously. You rarely need it outside tests.

## Using state outside components

`useState` and `observe` are also exported from `@realmorg/realm` for use in plain modules. Observers created there are not tied to any element, so stop them yourself with the function `observe` returns. For state shared between components, use a [store](/docs/stores/).


---

# `<is-visible>`

Source: http://realm.js.org/reference/elements/is-visible/

Mounts its content while a condition is true and removes it while it is false. Laid out with `display: contents`. Used in component markup. [`<is-hidden>`](/reference/elements/is-hidden/) is the inverse.

```html
<is-visible when="#ref" [eq|neq|gt|gte|lt|lte|contains="value"]>
  …content…
</is-visible>
```

## Attributes

| Attribute | Type | Meaning |
| --- | --- | --- |
| `when` | [reference](/reference/syntax/) | The value to test. Required. Without a comparison, the condition is "truthy" |
| `eq` | text | `String(value) === eq` |
| `neq` | text | `String(value) !== neq` |
| `gt` | number | `Number(value) > Number(gt)` |
| `gte` | number | `Number(value) >= Number(gte)` |
| `lt` | number | `Number(value) < Number(lt)` |
| `lte` | number | `Number(value) <= Number(lte)` |
| `contains` | text | An array has an item whose `String(item)` equals the text, or a string includes the text |

Use at most one comparison attribute. If there are several, the first in the order above is used.

## Mounting

- While the condition is false, the content is not in the DOM. Its bindings, handlers, observers and requests do not exist.
- When it becomes true, the content is created fresh. When it becomes false again, the content is removed and everything inside it stops.
- To keep content in the DOM and only hide it, bind `hidden` instead: `<div _hidden="!#panel.open">`.

## Example

```html live
<custom-element name="stock-level">
  <script type="realm">
    const stock = useState({ count: 3 });
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      justify-items: start;
    }
  </style>

  <ui-button onclick="stock.count = (stock.count + 1) % 6">Count: <slot name="#stock.count"></slot></ui-button>
  <is-visible when="#stock.count" eq="0"><p>Sold out.</p></is-visible>
  <is-visible when="#stock.count" lte="2"><p>Only a few left.</p></is-visible>
  <is-visible when="#stock.count" gt="2"><p>In stock.</p></is-visible>
</custom-element>

<stock-level></stock-level>
```

## Related

- [Control flow](/docs/control-flow/)
- [`<is-hidden>`](/reference/elements/is-hidden/)


---

# Values and bindings

Source: http://realm.js.org/docs/bindings/

Markup never contains expressions. It contains **references** to values from the script or props, and REALM keeps them up to date.

## References

| Reference | Reads |
| --- | --- |
| `#todo.draft` | `draft` on the top-level script name `todo` (state, a store, a getter, any top-level `const`, `let`, `function` or import) |
| `#item.title` | A loop variable inside `repeat` or `<repeat-list>` |
| `#todo.items.length` | Any property path, including `length` |
| `@heading` | The prop `heading` from `defineProps` |
| `!#panel.open` | The negation of a reference. `!` is the only operator |

A reference is resolved in the component whose markup contains it first, then in its parent components. See [Nested components and scope](/docs/scope/). An unknown name logs a warning and shows the slot's fallback content.

Only reactive values update. A top-level `const filters = [...]` can be referenced, but changes to a plain array are not seen. Put changing values in `useState`.

## Showing values: slots

A `<slot>` whose name starts with `#` or `@` shows that value as its content:

```html
<p>Hello, <slot name="@name"></slot></p>
<p><slot name="#todo.remaining"></slot> left</p>
<p><slot name="#user.name">Guest</slot></p>
```

- The value is shown as **text**. Numbers, `0` and `false` are shown as they are.
- While the value is `""`, `null` or `undefined`, the slot shows its own children, `Guest` above. This is the native fallback content of `<slot>`.
- The slot stays a `<slot>` element inside the shadow root. Nothing is added outside the component.
- Slots without `#` or `@`, such as `<slot>` and `<slot name="footer">`, are ordinary native slots for content placed inside the component.

### HTML values

Add `html` to show the value as HTML. It is sanitised first: `<script>`, `<style>`, `<iframe>`, `<object>`, `<embed>`, `<link>`, `<meta>`, `<base>`, `<template>` and `<noscript>` are removed, along with every `on*` attribute, `srcdoc`, and `javascript:`, `vbscript:` and `data:text/html` URLs.

```html
<div><slot name="#post.body" html></slot></div>
```

`html-unsafe` inserts the value without sanitising. Only use it for HTML you produced yourself. Inserted HTML is never scanned for handlers, references or bindings.

```html live
<custom-element name="html-preview">
  <script type="realm">
    const post = useState({
      body: '<p>Some <strong>bold</strong> text and <a href="javascript:alert(1)" onclick="alert(2)">a link</a>.</p><script>alert(3)<\/script>',
    });

    function edit(field) {
      post.body = field.value;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      width: min(calc(var(--spacing) * 120), 100%);
    }
    .output {
      padding: calc(var(--spacing) * 3);
      border: 1px solid var(--border);
      border-radius: var(--radius-md);
    }
  </style>

  <ui-textarea aria-label="HTML source" _value="#post.body" oninput="edit(this)"></ui-textarea>
  <div class="output"><slot name="#post.body" html></slot></div>
</custom-element>

<html-preview></html-preview>
```

The `javascript:` URL, the `onclick` attribute and the `<script>` never reach the page.

### Values in SVG

A value slot inside `<svg>` is replaced with a text node, so `<text><slot name="#chart.label"></slot></text>` works.

## Binding attributes: the _ prefix

`_` followed by an attribute name binds that attribute to a reference:

```html
<a _href="#link.url">Open</a>
<section _hidden="!#panel.open">…</section>
<button _disabled="@disabled">Save</button>
<li _data-done="#item.done" _aria-selected="#item.selected">…</li>
<input _value="#form.email">
<user-card _user="#session.user"></user-card>
<div _--progress="#upload.percent"></div>
```

How each value is applied:

| Target | Rule |
| --- | --- |
| Any attribute | `true` adds it with an empty value, `false`, `null` and `undefined` remove it, anything else is written as text |
| `aria-*`, `draggable`, `spellcheck`, `contenteditable` | Booleans are written as `"true"` and `"false"` |
| `value`, `checked`, `selected`, `indeterminate` on elements that have that property | Sets the **property**, so the field's current value changes, not only its default |
| A custom element (any tag with a dash) with an object or array value | Sets the property (`_user-data` sets `userData`), so the object arrives intact |
| `--name` | Sets a CSS custom property on the element's inline style |
| SVG attributes | Case is restored for attributes such as `viewBox` |

### Changes come back through events

Bindings are one-way. To update state from a field, handle its native event:

```html
<input _value="#todo.draft" oninput="updateDraft(this)">
```

```js
function updateDraft(field) {
  todo.draft = field.value;
}
```

There is no hidden two-way binding, so it is always clear where a value is written.

### The class attribute

`_class="#theme.className"` replaces the whole `class` value. To toggle a single class, prefer a data attribute (`_data-active="#tab.active"`) and select it in CSS, or use a [reactive CSS state](/docs/styling/#reactive-states).

## References in other attributes

The same reference syntax is used by:

- `<is-visible when>` and `<is-hidden when>`: [Control flow](/docs/control-flow/)
- `repeat` and `<repeat-list of>`: [Lists and keys](/docs/lists/)
- `into`, `busy`, `headers` and `params`: [Fetching data](/docs/fetching/)

`ref="name"` is not a reference. It registers the element in the script's `refs` object.


---

# `<is-hidden>`

Source: http://realm.js.org/reference/elements/is-hidden/

The inverse of [`<is-visible>`](/reference/elements/is-visible/). It mounts its content while the condition is **false**. Laid out with `display: contents`. Used in component markup.

```html
<is-hidden when="#ref" [eq|neq|gt|gte|lt|lte|contains="value"]>
  …content…
</is-hidden>
```

## Attributes

The same as `<is-visible>`. The condition is evaluated the same way and the result is inverted.

| Attribute | Type | Content is mounted when |
| --- | --- | --- |
| `when` | [reference](/reference/syntax/) | Required. Alone: the value is falsy |
| `eq` | text | `String(value) !== eq` |
| `neq` | text | `String(value) === neq` |
| `gt` | number | not `Number(value) > Number(gt)` |
| `gte` | number | not `Number(value) >= Number(gte)` |
| `lt` | number | not `Number(value) < Number(lt)` |
| `lte` | number | not `Number(value) <= Number(lte)` |
| `contains` | text | The array or string does not contain the text |

`<is-hidden when="#x">` is the same as `<is-visible when="!#x">`. Use whichever reads better.

## Example

```html live
<custom-element name="todo-empty">
  <script type="realm">
    const todo = useState({ items: [] });

    function add() {
      todo.items.push(`Task ${todo.items.length + 1}`);
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      justify-items: start;
    }
  </style>

  <ui-button onclick="add()">Add task</ui-button>
  <is-hidden when="#todo.items.length"><p>Nothing to do.</p></is-hidden>
  <is-hidden when="#todo.items.length" lt="3"><p>That is a lot of tasks.</p></is-hidden>
</custom-element>

<todo-empty></todo-empty>
```

## Related

- [Control flow](/docs/control-flow/)


---

# Events

Source: http://realm.js.org/docs/events/

REALM uses the browser's own event model. Handlers are native `on*` attributes, events are emitted with `dispatchEvent`, and anything that listens with `addEventListener` keeps working.

## Handling events in markup

Write native handler attributes. Function names resolve to the component's script:

```html
<button onclick="save()">Save</button>
<input oninput="search(this.value)">
<form onsubmit="add(event)">…</form>
<li repeat="#todo.items" as="item" key="id" onclick="toggle(item)">…</li>
```

- `event` is the event and `this` is the element, as in plain HTML.
- Inside `repeat` or `<repeat-list>`, the loop variables (`item`, and the `index` name if you set one) are in scope.
- `return false` cancels the event, like a native handler.
- Names that the script does not define are looked up in parent components, then globals, so `console.log(event)` or `history.back()` work.

Keep handlers to a single function call. Logic belongs in the script.

Handlers are compiled together with the script when the component type is defined, not from the attribute at runtime, and the `on*` attribute is removed from the rendered element. They are not inline handler attributes as far as the browser is concerned, so a Content Security Policy that blocks inline handlers does not block them. See [Security](/docs/security/).

### Debounce and throttle

`debounce` and `throttle` attributes time every handler on that element:

```html
<input oninput="search(this.value)" debounce="300ms">
<div onscroll="measure()" throttle="100ms"></div>
```

Durations accept `ms`, `s` and `m` (`250ms`, `2s`, `1m`). A bare number is milliseconds. Pending debounced calls are cancelled when the element is removed.

## Emitting events

Emit events from the host with the native `dispatchEvent`, or with the `dispatch` helper, which creates a `CustomEvent` that bubbles, crosses shadow roots (`composed`) and is cancelable, and returns `false` when a listener called `preventDefault()`:

```js
function choose(option) {
  if (!dispatch("pick", { value: option.value })) return; // a listener cancelled it
  props.value = option.value;
}
```

`dispatch(type, detail, options)` accepts the usual `CustomEvent` options to override the defaults, for example `{ bubbles: false, composed: false }`.

Name events like native ones: lowercase, without dashes, so `on` plus the name reads like a native handler (`pick` → `onpick`, `requestclose` → `onrequestclose`).

## Handling a component's events

### Inside another component

A parent handles a child's events with `on<name>` in its markup, whether the name is native or not:

```html
<rating-stars onrate="saveRating(event.detail.value)"></rating-stars>
```

### On a plain page

Browsers only support handler attributes for native event names. REALM adds them for its components. On a plain page, an `on<name>` attribute on a REALM element holds ordinary JavaScript, and the matching property accepts a function, like `onclick`:

```html live
<custom-element name="rating-stars">
  <script type="realm">
    const props = defineProps({ value: prop.number().int().min(0).max(5).default(0) });

    const stars = useState({
      get list() {
        return [1, 2, 3, 4, 5].map((value) => ({ value, on: value <= props.value, label: `${value} stars` }));
      },
    });

    function rate(star) {
      const event = new CustomEvent("rate", { bubbles: true, composed: true, cancelable: true, detail: { value: star.value } });
      if (host.dispatchEvent(event)) props.value = star.value;
    }
  </script>

  <style type="realm">
    :host {
      display: inline-flex;
    }
    button {
      all: unset;
      cursor: pointer;
      padding: calc(var(--spacing) * 0.5);
      font-size: var(--text-2xl);
      line-height: 1;
      color: var(--muted-foreground);
    }
    button[data-on] {
      color: var(--chart-4);
    }
    button:focus-visible {
      border-radius: var(--radius-sm);
      box-shadow: var(--focus-ring);
    }
  </style>

  <repeat-list of="#stars.list" as="star" key="value">
    <button type="button" _aria-label="#star.label" _data-on="#star.on" onclick="rate(star)">★</button>
  </repeat-list>
</custom-element>

<rating-stars value="3" onrate="document.getElementById('rating-out').value = 'You rated ' + event.detail.value"></rating-stars>
<output id="rating-out">Click a star.</output>
```

The attribute and the property stay in sync, the handler runs in its native position among listeners, `return false` cancels, and `addEventListener` works alongside:

```js
const stars = document.querySelector("rating-stars");
stars.onrate = (event) => {
  if (event.detail.value < 2) event.preventDefault();
};
```

REALM finds a component's custom event names by reading its script for `new CustomEvent("name"` and `new Event("name"`. Native names such as `change`, `input`, `toggle`, `select` and `close` are never redefined, because they already work everywhere.

## Listening from the script

`listen(type, handler, target)` adds a listener that is removed when the element is removed. The target defaults to the host:

```js
listen("keydown", (event) => {
  if (event.key === "Escape") close();
});

listen("toast", (event) => show(event.detail), document);
```

Use it instead of `addEventListener` so you never leak listeners on `document` or `window`. For listeners you add yourself, pass the `signal` helper: `target.addEventListener(type, fn, { signal })`.

## Public methods

`defineMethods(object)` adds methods and getters to the element, so page code and parent components can call them. They are removed when the element is torn down.

```html live
<custom-element name="tally-counter">
  <script type="realm">
    const tally = useState({ count: 0 });

    defineMethods({
      increment(by = 1) {
        tally.count += by;
        return tally.count;
      },
      reset() {
        tally.count = 0;
      },
      get count() {
        return tally.count;
      },
    });
  </script>

  <style type="realm">
    :host {
      font-size: var(--text-2xl);
      font-weight: var(--font-weight-semibold);
      font-variant-numeric: tabular-nums;
    }
  </style>

  <slot name="#tally.count"></slot>
</custom-element>

<tally-counter id="tally"></tally-counter>
<ui-button onclick="document.getElementById('tally').increment()">Add one</ui-button>
<ui-button variant="outline" onclick="document.getElementById('tally').increment(10)">Add ten</ui-button>
<ui-button variant="ghost" onclick="document.getElementById('tally').reset()">Reset</ui-button>
```

The buttons here are plain page markup, so their handlers are ordinary page JavaScript.

## Events from requests and imports

Elements with [fetch attributes](/docs/fetching/) fire `loadstart`, `load`, `error`, `abort`, `timeout` and `loadend`. `<import-element>` fires `load` and `error`. Handle them with the same native attributes, such as `onload="clearDraft()"`.


---

# Control flow

Source: http://realm.js.org/docs/control-flow/

`<is-visible>` and `<is-hidden>` add or remove their content based on a reference.

```html
<is-visible when="#cart.isEmpty">
  <p>Your cart is empty.</p>
</is-visible>

<is-hidden when="#cart.isEmpty">
  <cart-list></cart-list>
</is-hidden>
```

| Tag | Content is present when |
| --- | --- |
| `<is-visible when="#ref">` | the value is truthy (or the comparison is true) |
| `<is-hidden when="#ref">` | the value is falsy (or the comparison is false) |

Content that is not shown is **removed** from the DOM, not hidden with CSS. Its bindings, listeners, requests and nested components stop, and they start fresh when the content comes back. Both tags lay out as if they were not there (`display: contents`).

## Comparisons

For simple cases, compare the value with one of these attributes instead of writing a getter:

| Attribute | True when |
| --- | --- |
| `eq="text"` | `String(value) === "text"` |
| `neq="text"` | `String(value) !== "text"` |
| `gt="n"`, `gte="n"` | the value as a number is greater than (or equal to) `n` |
| `lt="n"`, `lte="n"` | the value as a number is less than (or equal to) `n` |
| `contains="text"` | an array has an item equal to `text`, or a string includes `text` |

```html live
<custom-element name="order-status">
  <script type="realm">
    const STEPS = ["placed", "packed", "shipped", "delivered"];

    const order = useState({
      step: 0,
      tags: ["gift"],
      get status() {
        return STEPS[this.step];
      },
    });

    function next() {
      order.step = (order.step + 1) % STEPS.length;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      justify-items: start;
    }
  </style>

  <p>Status: <strong><slot name="#order.status"></slot></strong></p>
  <is-visible when="#order.status" eq="shipped"><p>On its way.</p></is-visible>
  <is-visible when="#order.step" gte="2"><ui-badge variant="secondary">Tracking available</ui-badge></is-visible>
  <is-hidden when="#order.status" neq="delivered"><p>Delivered. Enjoy!</p></is-hidden>
  <is-visible when="#order.tags" contains="gift"><p>Gift wrapped.</p></is-visible>
  <ui-button size="sm" onclick="next()">Next step</ui-button>
</custom-element>

<order-status></order-status>
```

Anything more involved belongs in a getter, which keeps the markup free of logic:

```js
const order = useState({
  items: [],
  get canCheckout() {
    return this.items.length > 0 && this.items.every((item) => item.inStock);
  },
});
```

```html
<is-visible when="#order.canCheckout"><ui-button>Checkout</ui-button></is-visible>
```

`!` works in `when` too: `<is-visible when="!#user.signedIn">`.

## Hiding without removing

To keep content in the DOM (for example to keep a form's typed values, or a playing video), bind the native `hidden` attribute instead:

```html
<section _hidden="!#panel.open">…</section>
```

## Choosing between several cases

There is no `else if` tag. Map the case to a value in the script and compare it with `eq`, or use a lookup table that produces what the markup needs:

```js
const VIEWS = {
  loading: { title: "Loading…", tone: "muted" },
  error: { title: "Something went wrong", tone: "destructive" },
  ready: { title: "Up to date", tone: "default" },
};

const status = useState({
  state: "loading",
  get view() {
    return VIEWS[this.state];
  },
});
```

```html
<is-visible when="#status.state" eq="error"><ui-button onclick="retry()">Retry</ui-button></is-visible>
<p _data-tone="#status.view.tone"><slot name="#status.view.title"></slot></p>
```

## Inside tables and selects

The HTML parser moves unknown elements out of `<table>`, `<tr>` and `<select>`. Do not put `<is-visible>` there. Bind `_hidden` on the row or option instead, or filter the list in a getter and [repeat](/docs/lists/) over the result.

## Recursive components

A component can render itself, which is how trees such as folders or comment threads are built. Put the nested copy inside a condition that eventually turns false, here when a node has no children:

```html live
<custom-element name="file-tree">
  <script type="realm">
    const props = defineProps({
      node: prop.object().default({ name: "src", children: [{ name: "lib", children: [{ name: "store.js" }] }, { name: "app.html" }] }),
    });
    const tree = useState({
      get children() {
        return props.node.children ?? [];
      },
      get hasChildren() {
        return this.children.length > 0;
      },
    });
  </script>

  <style type="realm">
    ul {
      margin: 0;
      padding-left: calc(var(--spacing) * 4);
    }
  </style>

  <slot name="@node.name"></slot>
  <is-visible when="#tree.hasChildren">
    <ul>
      <li repeat="#tree.children" as="child" key="name"><file-tree _node="#child"></file-tree></li>
    </ul>
  </is-visible>
</custom-element>

<file-tree></file-tree>
```

Trees can be as deep as your data. A component nested more than 1000 components deep is not set up, and the console warns `<file-tree> is nested 1000 deep. Stop its recursion with a condition.` That almost always means the component renders itself with nothing to stop it.



---

# Value slots

Source: http://realm.js.org/reference/elements/value-slots/

A native `<slot>` whose `name` is a [reference](/reference/syntax/) shows that value. It stays a `<slot>` element in the shadow root and updates when the value changes.

```html
<slot name="#state.path" [html | html-unsafe]>fallback</slot>
<slot name="@prop">fallback</slot>
<slot name="!#state.flag"></slot>
```

A slot whose name does not start with `#`, `@` or `!` (`<slot>`, `<slot name="footer">`) is an ordinary slot for light DOM content.

## Attributes

| Attribute | Type | Default | Meaning |
| --- | --- | --- | --- |
| `name` | reference | required | The value to show |
| `html` | boolean | absent | Show the value as sanitised HTML |
| `html-unsafe` | boolean | absent | Show the value as HTML without sanitising. Only for HTML you produced yourself |

When both are present, `html-unsafe` wins.

## Modes

| Mode | How the value is shown |
| --- | --- |
| text (default) | `String(value)` as a text node. `0`, `false` and numbers are shown as they are |
| `html` | Parsed and cleaned, then inserted. Removed: `<script>`, `<style>`, `<iframe>`, `<frame>`, `<frameset>`, `<object>`, `<embed>`, `<link>`, `<meta>`, `<base>`, `<template>`, `<noscript>`, every `on*` attribute, `srcdoc`, and `javascript:`, `vbscript:` and `data:text/html` URLs in `href`, `src`, `action`, `formaction`, `xlink:href`, `poster`, `to`, `from` and `values` |
| `html-unsafe` | Assigned to `innerHTML` as is |

Inserted HTML is never scanned for references, bindings or handlers.

## Fallback

While the value is `""`, `null` or `undefined`, the slot shows its own children, the same as native slot fallback content:

```html
<p>Signed in as <slot name="#user.name">guest</slot></p>
```

## Inside SVG

A text-mode value slot inside `<svg>` is replaced with a text node, so `<text><slot name="#chart.label"></slot></text>` works. With `html` or `html-unsafe`, the slot becomes a `<g>` holding the parsed SVG elements (sanitised for `html`).

## Example

```html live
<custom-element name="greeting-card">
  <script type="realm">
    const props = defineProps({ name: prop.string() });
    const note = useState({ body: "<em>Welcome</em> back. <a href='javascript:alert(1)' onclick='alert(2)'>Unsafe link</a>" });
  </script>

  <p>Hello, <slot name="@name">stranger</slot>.</p>
  <p><slot name="#note.body" html></slot></p>
  <p><code><slot name="#note.body"></slot></code></p>
</custom-element>

<greeting-card name="Ada"></greeting-card>
<greeting-card></greeting-card>
```

## Related

- [Values and bindings](/docs/bindings/)
- [Security](/docs/security/)


---

# Lists and keys

Source: http://realm.js.org/docs/lists/

REALM repeats content with `<repeat-list>`, or with the `repeat` attribute on the element to repeat.

```html
<repeat-list of="#todo.items" as="item" index="i" key="id">
  <article>
    <h3><slot name="#item.title"></slot></h3>
    <p>Item <slot name="#i"></slot></p>
  </article>
</repeat-list>

<ul>
  <li repeat="#todo.items" as="item" key="id"><slot name="#item.title"></slot></li>
</ul>
```

| Attribute | Meaning | Default |
| --- | --- | --- |
| `of` (on `<repeat-list>`) or `repeat` (on any element) | A reference to an array | |
| `as` | Name of the item variable | `item` |
| `index` | Name of the index variable, if you need one | none |
| `key` | Name of a property that identifies each item | the position |

Inside each copy:

- `#item.title` and `#i` work in slots, bindings and conditions.
- `item` and `i` are variables in event handlers: `onclick="remove(item)"`.
- Everything else still resolves to the component's script, so `#todo.filter` works inside the loop too.

A value that is not an array renders nothing.

## Which form to use

`<repeat-list>` lays out as if it were not there (`display: contents`) and can repeat several elements per item. Use it anywhere unknown elements are allowed.

Use the `repeat` attribute **inside `<ul>`, `<ol>`, `<table>`, `<tbody>`, `<tr>` and `<select>`**. The HTML parser moves unknown tags such as `<repeat-list>` out of tables and selects, and lists only allow `<li>` children.

```html
<table>
  <tbody>
    <tr repeat="#report.rows" as="row" key="id">
      <td><slot name="#row.name"></slot></td>
      <td><slot name="#row.total"></slot></td>
    </tr>
  </tbody>
</table>

<select>
  <option repeat="#form.countries" as="country" key="code" _value="#country.code"><slot name="#country.name"></slot></option>
</select>
```

## Keys

With `key`, REALM matches items by that property between updates:

- an item that is still there keeps its DOM nodes, so focus, typed text, scroll position and running transitions survive,
- moved items are moved, not re-created,
- removed items are torn down, including their listeners and requests,
- new items are created.

Without `key`, items are matched by position, so changing the first item updates the first row in place. This is fine for static or append-only lists. Use a key when items can be reordered, inserted or removed.

Keys must be unique. A duplicate key logs a warning and the duplicate gets its own row.

```html live
<custom-element name="sortable-names">
  <script type="realm">
    const people = useState({
      list: [
        { id: 1, name: "Ana" },
        { id: 2, name: "Bo" },
        { id: 3, name: "Chen" },
      ],
    });

    function shuffle() {
      people.list.sort(() => Math.random() - 0.5);
    }

    function addFirst() {
      const id = people.list.length + 1;
      people.list.unshift({ id, name: `Person ${id}` });
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      width: min(calc(var(--spacing) * 96), 100%);
    }
    ol {
      margin: 0;
      padding-left: calc(var(--spacing) * 5);
    }
    li {
      padding: calc(var(--spacing) * 1) 0;
    }
    li ui-input {
      display: inline-block;
      width: calc(var(--spacing) * 56);
      margin-left: calc(var(--spacing) * 2);
      vertical-align: middle;
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
  </style>

  <ol>
    <li repeat="#people.list" as="person" key="id">
      <slot name="#person.name"></slot>
      <ui-input aria-label="Note" placeholder="Type a note, then shuffle"></ui-input>
    </li>
  </ol>
  <div class="actions">
    <ui-button size="sm" onclick="shuffle()">Shuffle</ui-button>
    <ui-button size="sm" variant="outline" onclick="addFirst()">Add first</ui-button>
  </div>
</custom-element>

<sortable-names></sortable-names>
```

Type a note, then shuffle. The note stays with its person because the row is moved, not rebuilt.

## Updating lists

Change the array in the script. All mutating array methods are tracked:

```js
todo.items.push(item);
todo.items.splice(index, 1);
todo.items.sort((a, b) => a.title.localeCompare(b.title));
todo.items = todo.items.filter((item) => !item.done); // replacing works too
item.done = true; // changing a field updates only what reads it
```

When a keyed item is replaced by a new object with the same key, its row is kept and its bindings show the new object's values.

## Filtered and sorted views

Keep the source array as it is and expose a getter for what the markup shows:

```js
const todo = useState({
  items: [],
  filter: "all",
  get visible() {
    return this.items.filter(FILTERS[this.filter]);
  },
});
```

```html
<li repeat="#todo.visible" as="item" key="id">…</li>
```

## Nested loops

Loops nest. Inner loops can use outer variables:

```html
<repeat-list of="#board.columns" as="column" key="id">
  <section>
    <h3><slot name="#column.title"></slot></h3>
    <ul>
      <li repeat="#column.cards" as="card" key="id" onclick="open(column, card)"><slot name="#card.title"></slot></li>
    </ul>
  </section>
</repeat-list>
```


---

# Lifecycle

Source: http://realm.js.org/docs/lifecycle/

REALM follows the native custom element lifecycle. The constructor does nothing. All setup runs when the element is connected to the page.

## When an element connects

1. A shadow root is created (once per element) and the component's stylesheets are adopted.
2. The script runs for this instance. `host`, `signal` and `internals` are ready. `refs` is still empty because the markup does not exist yet.
3. The markup is cloned, and every slot, binding, handler, condition, loop and fetch attribute is connected.
4. `onConnected` callbacks run. `refs` now holds every element with a `ref` attribute.

```js
const editor = useState({ ready: false });

onConnected(() => {
  refs.input.focus();
  const observer = new ResizeObserver(() => measure());
  observer.observe(host);
  return () => observer.disconnect(); // runs when the element is removed
});
```

A function returned from `onConnected` runs on removal.

`refs` is reactive, so an `observe` at the top of the script sees each ref as soon as the markup exists:

```js
observe(() => {
  if (refs.canvas) draw(refs.canvas);
});
```

## When an element is removed

Removal is handled one microtask later, so a move (remove, then insert again in the same task) is not a removal:

- **Moved** to another place in the page: the instance, its state and its DOM are kept.
- **Removed**: `onDisconnected` callbacks run, then the element's `signal` aborts, every observer stops, every listener, timer, poll and request REALM created is cancelled, prop accessors and methods added with `defineMethods` are removed, and the shadow root is emptied.
- **Added again later**: it mounts fresh, with new state, as if it were new.

```js
onDisconnected(() => {
  saveDraft();
});
```

## signal

`signal` is an `AbortSignal` that aborts when the element is removed. Pass it to anything you start yourself:

```js
const response = await fetch("/api/report", { signal });

window.addEventListener("resize", measure, { signal });

const id = setInterval(poll, 5000);
signal.addEventListener("abort", () => clearInterval(id));
```

The `listen` helper does this for listeners. For timers, return a cleanup function from `observe`.

## host, refs and internals

| Helper | What it is |
| --- | --- |
| `host` | The element itself. Use it for `host.dispatchEvent`, `host.getRootNode()`, `host.closest(...)` |
| `refs` | An object of elements marked with `ref="name"` in the markup |
| `internals` | The element's `ElementInternals`: `states`, `role`, `setFormValue`, `setValidity`, `form`, `labels` |

`internals.states` drives custom CSS states:

```js
observe(() => {
  if (menu.open) internals.states.add("open");
  else internals.states.delete("open");
});
```

```css
:host(:state(open)) .panel {
  display: block;
}
```

While a [fetch attribute](/docs/fetching/) request runs inside a component, its host matches `:state(loading)`.

## Form lifecycle

Form-associated components also get `onFormReset`, `onFormDisabled` and `onFormStateRestore`. See [Forms](/docs/forms/).

## Elements inside definitions

Elements written inside a `<custom-element>` definition in the page are never mounted while they are part of the definition. They mount once the definition is used.


---

# Nested components and scope

Source: http://realm.js.org/docs/scope/

Components can nest. A reference such as `#session.user` or a handler name such as `logout` resolves in this order:

1. loop variables of the surrounding `repeat` or `<repeat-list>`,
2. the component whose markup contains the reference (its owner),
3. each parent component, from the nearest outwards,
4. for handler names only: globals, such as `console` or `history`.

## Content belongs to its owner

Content you place inside a child component is still yours. Here `#todo.remaining` is written in `todo-app`'s markup, so it reads `todo-app`'s state, even though it is displayed inside `ui-card`:

```html
<custom-element name="todo-app">
  <script>
    const todo = useState({
      items: [],
      get remaining() {
        return this.items.filter((item) => !item.done).length;
      },
    });
  </script>

  <ui-card>
    <ui-card-header>
      <ui-card-title>Today</ui-card-title>
    </ui-card-header>
    <ui-card-content><slot name="#todo.remaining"></slot> left</ui-card-content>
  </ui-card>
</custom-element>
```

This is standard shadow DOM. The value slot lives in `todo-app`'s shadow root and is projected into `ui-card` through `ui-card`'s own `<slot>`.

## Parents fill in missing names

When the owner does not define a name, REALM looks in the component that contains it, then that component's parent, and so on. A deeply nested component can read shared values without passing them through every level:

```html live
<custom-element name="app-shell">
  <script type="realm">
    const session = useState({ user: "Ana" });

    function signOut() {
      session.user = "";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
    }
  </style>

  <nav-bar></nav-bar>
</custom-element>

<custom-element name="nav-bar">
  <style type="realm">
    :host {
      display: flex;
      gap: calc(var(--spacing) * 3);
      align-items: center;
    }
  </style>

  <span>Signed in as <slot name="#session.user">nobody</slot></span>
  <ui-button size="sm" variant="outline" onclick="signOut()">Sign out</ui-button>
</custom-element>

<app-shell></app-shell>
```

`nav-bar` has no `session` and no `signOut`, so both resolve to `app-shell`. REALM logs a one-time console warning for each name read from a parent (`<nav-bar> reads "session" from <app-shell>.`), so you can see where implicit sharing happens.

Rules:

- A component's own names always win over a parent's.
- A name that no component defines logs a warning and shows the slot's fallback content.
- The lookup follows the composed tree, so it works through shadow roots and slots.

## Pass data explicitly for reusable components

Parent lookup is convenient inside one app. For components you reuse elsewhere, make the contract explicit with props and events:

```html
<user-menu _user="#session.user" onsignout="signOut()"></user-menu>
```

Objects and arrays passed with `_` bindings arrive as properties, intact. The child declares them with `defineProps` and emits events with `dispatch` or `dispatchEvent`.

## App-wide state

State that several unrelated components need, or that should outlive a component, belongs in a [store](/docs/stores/).


---

# `_` bindings

Source: http://realm.js.org/reference/attributes/bindings/

`_` followed by an attribute name binds that attribute to a [reference](/reference/syntax/). The binding is one-way: it follows the value whenever it changes. Used on any element in component markup.

```html
<element _name="#ref"></element>
<element _name="!#ref"></element>
<element _--custom-property="#ref"></element>
```

```html
<a _href="#link.url">Open</a>
<section _hidden="!#panel.open">…</section>
<button _disabled="@disabled">Save</button>
<input _value="#form.email">
<user-card _user="#session.user"></user-card>
<div _--progress="#upload.percent"></div>
```

The `_name` attribute itself is removed when the markup is processed. The value must be a reference. Anything else logs a warning and the binding is skipped.

## How values are applied

The first matching rule wins:

| Target | Value | Result |
| --- | --- | --- |
| `_--name` | `null`, `undefined`, `false` | `style.removeProperty("--name")` |
| `_--name` | anything else | `style.setProperty("--name", String(value))` |
| `value` on `<progress>` or `<meter>` | `null`, `undefined` | Attribute removed, so the element stays indeterminate |
| `value`, `checked`, `selected`, `indeterminate` on an element with that property | any | Sets the **property**. `value` gets `value ?? ""`. The others get `Boolean(value)` |
| Any attribute of a custom element (tag with a dash) | object or array | Sets the camelCase **property** (`_user-data` sets `userData`), so the object arrives intact |
| `aria-*`, `draggable`, `spellcheck`, `contenteditable` | `true`, `false` | Attribute set to `"true"` or `"false"` |
| Any attribute | `true` | Attribute set to `""` |
| Any attribute | `false`, `null`, `undefined` | Attribute removed |
| Any attribute | anything else | Attribute set to `String(value)` |

On SVG elements, the attribute name's case is restored for camelCase SVG attributes such as `viewBox`, `preserveAspectRatio`, `gradientTransform`, `stdDeviation` and `textLength`, so `_viewbox` and `_viewBox` both work.

## Changes come back through events

Bindings never write back to state. Update state from a handler:

```html
<input _value="#todo.draft" oninput="todo.draft = this.value">
```

## class

`_class` replaces the whole `class` attribute. To toggle one style, bind a data attribute and select it in CSS (`_data-active="#tab.active"`), or use a [reactive `:state()`](/reference/css/states/).

## Example

```html live
<custom-element name="volume-meter">
  <script type="realm">
    const level = useState({
      value: 40,
      get loud() {
        return this.value > 70;
      },
    });
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      width: min(calc(var(--spacing) * 80), 100%);
    }
    .bar {
      height: calc(var(--spacing) * 2);
      width: calc(var(--level) * 1%);
      border-radius: var(--radius-full);
      background: var(--primary);
    }
    .bar[data-loud] {
      background: var(--destructive);
    }
  </style>

  <input type="range" min="0" max="100" aria-label="Volume" _value="#level.value" oninput="level.value = Number(this.value)">
  <div class="bar" _--level="#level.value" _data-loud="#level.loud" _aria-label="#level.value" role="img"></div>
</custom-element>

<volume-meter></volume-meter>
```

## Related

- [Values and bindings](/docs/bindings/)
- [Value slots](/reference/elements/value-slots/)


---

# Fetching data

Source: http://realm.js.org/docs/fetching/

Requests are attributes on the element that triggers them. The response goes into state (`into`) or into the page as HTML (`render`), and the element fires the browser's resource events (`load`, `error`, …) so you handle results with ordinary handlers.

Fetch attributes work on elements in a component's markup.

```html
<!-- load JSON into state when the component appears -->
<ul fetch="/api/todos" trigger="load" into="#todo.items" busy="#todo.loading">
  <li repeat="#todo.items" as="item" key="id"><slot name="#item.title"></slot></li>
</ul>

<!-- search as you type -->
<input type="search" name="q" fetch="/api/search" trigger="input" debounce="300ms" into="#search.results">

<!-- server-rendered HTML into an element -->
<button fetch="/partials/comments?page=2" render="comments" render-mode="append">Load more</button>
<div ref="comments"></div>

<!-- forms use their native action and method -->
<form action="/todos" method="post" into="#todo.items" into-mode="append" onload="clearDraft()">
  <input name="text" required>
  <button>Add</button>
</form>
```

## Loading JSON into state

This demo loads this site's search index when it appears and filters it as you type:

```html live
<custom-element name="page-finder">
  <script type="realm">
    const index = useState({
      pages: [],
      loading: false,
      query: "",
      get matches() {
        const query = this.query.trim().toLowerCase();
        return this.pages.filter((page) => page.title.toLowerCase().includes(query)).slice(0, 6);
      },
      get summary() {
        return `${this.matches.length} shown of ${this.pages.length} pages`;
      },
    });

    function search(field) {
      index.query = field.value;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      width: min(calc(var(--spacing) * 120), 100%);
    }
    ul {
      margin: 0;
      padding-left: calc(var(--spacing) * 5);
    }
    small {
      color: var(--muted-foreground);
    }
  </style>

  <div hidden fetch="/search-index.json" trigger="load" into="#index.pages" busy="#index.loading"></div>
  <ui-input type="search" aria-label="Filter pages" placeholder="Filter pages by title" oninput="search(this)" debounce="150ms"></ui-input>
  <is-visible when="#index.loading"><ui-spinner></ui-spinner></is-visible>
  <ul>
    <li repeat="#index.matches" as="page" key="url"><slot name="#page.title"></slot> <small><slot name="#page.section"></slot></small></li>
  </ul>
  <small><slot name="#index.summary"></slot></small>
</custom-element>

<page-finder></page-finder>
```

JSON responses (by `Content-Type`) are parsed. Anything else arrives as text.

## Refetching when state changes

A reference in `trigger` re-runs the request whenever that value changes. Here the forecast reloads as soon as a place is chosen, with no script:

```html
<form fetch="/api/forecast" trigger="change submit #place" params="lat:#place.latitude, lon:#place.longitude" into="#weather.data">
  …
</form>
```

The first value doesn't trigger a request (add `load` for that), and writes that leave the value unchanged are ignored. `debounce` and `throttle` apply.

## Updating one item in a list

After saving or deleting a record, `into-mode="update"` and `into-mode="remove"` change only that item in a list already in state:

```html
<form action="/api/contacts/7" method="put" into="#list.items" into-mode="update">…</form>
<form action="/api/contacts/7" method="delete" into="#list.items" into-mode="remove">…</form>
```

Items are matched by `id`, or by the property named in `into-key`.

## Rendering HTML

`render="name"` inserts the response into the element marked `ref="name"`. The HTML is sanitised first and never scanned for handlers or bindings. `render-select` keeps only the matching part of the response.

```html live
<custom-element name="partial-loader">
  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: start;
      width: min(calc(var(--spacing) * 120), 100%);
    }
    .target {
      justify-self: stretch;
      min-height: calc(var(--spacing) * 10);
      padding: calc(var(--spacing) * 3);
      border: 1px dashed var(--border);
      border-radius: var(--radius-md);
    }
  </style>

  <ui-button size="sm" fetch="/404.html" render="target" render-select=".not-found h1, .not-found p:first-of-type" render-mode="append">Append a fragment</ui-button>
  <div class="target" ref="target"></div>
</custom-element>

<partial-loader></partial-loader>
```

| `render-mode` | Effect on the target |
| --- | --- |
| `replace` (default) | Replaces its children |
| `outer` | Replaces the target itself |
| `append`, `prepend` | Adds inside, at the end or start |
| `before`, `after` | Adds next to the target |
| `merge` | Updates children in place: unchanged nodes stay, changed attributes and text are patched, and a focused element and its content are left alone, so typing is never interrupted |
| `text` | Sets the target's text, no HTML |
| `remove` | Removes the target |

A link with `render` loads the page into the target and updates the address bar with `history.pushState`:

```html
<a href="/inbox?page=2" render="main" render-select="main > *">Next page</a>
<main ref="main">…</main>
```

## Attributes

| Attribute | Meaning | Default |
| --- | --- | --- |
| `fetch="url"` | Make a request to this URL. Resolved against the page. `_fetch="#ref"` binds it | Forms use `action`, links use `href` |
| `method` | `get`, `post`, `put`, `patch` or `delete` | `get`, forms use their native `method` |
| `trigger` | Events that start the request, separated by spaces or commas. Any event name, plus `load` (when the element is connected), `visible` (when it scrolls into view) and references such as `#place` or `@city` (whenever that value changes, including nested values) | `submit` on forms, `change` on inputs, selects and textareas, `click` elsewhere |
| `debounce`, `throttle` | Delay or limit repeated triggers, such as `300ms` | |
| `poll` | Repeat on an interval while the element is on the page, such as `30s` | |
| `params` | Extra values to send: `page:#list.page, sort:@order`. Objects are sent as JSON | |
| `headers` | A reference to a headers object: `headers="#auth.headers"` | |
| `into` | A writable state path for the response, such as `#todo.items` | |
| `into-mode` | `replace`, `append`, `prepend`, `update` or `remove`. Append and prepend add to an array, wrapping single values. Update replaces items with the same `into-key` and appends new ones. Remove takes them out | `replace` |
| `into-key` | The property that identifies list items for `update` and `remove` | `id` |
| `render` | The `ref` name of the element that receives the response as HTML | |
| `render-mode` | See the table above | `replace` |
| `render-select` | A CSS selector. Only matching elements of the response are inserted | |
| `busy` | A writable state path set to `true` while the request runs and `false` after | |
| `timeout` | Abort the request after this long, firing `timeout` | |

### What is sent

- A `<form>` sends its fields as native `FormData`, including [form-associated components](/docs/forms/). The submit button's `formaction` and `formmethod` override the form's.
- An `<input>`, `<select>` or `<textarea>` sends its own `name` and value.
- `params` adds more values.
- `GET` requests put everything in the query string. Other methods send `application/x-www-form-urlencoded`, or `multipart/form-data` when the form has `enctype="multipart/form-data"` (for file uploads).

## Events

The element fires the native resource-loading event names. They do not bubble, so handle them on the element:

| Event | When | `event.detail` |
| --- | --- | --- |
| `loadstart` | Before sending. Cancelable: `return false` or `preventDefault()` stops the request | `{ url, method }` |
| `load` | After a 2xx response, once `into` and `render` are applied | `{ status, data, headers, url }` |
| `error` | A non-2xx response or a network failure. Nothing is inserted | `{ status, data, headers, url }`, or `{ status: 0, message, url }` for network errors |
| `abort` | The request was cancelled by a newer one or by removal | `{ url }` |
| `timeout` | The `timeout` elapsed | `{ url }` |
| `loadend` | Always, at the end | `{ url }` |

```html
<button fetch="/api/items/7" method="delete" onloadstart="return confirm('Delete this item?')" onload="removed(event.detail)" onerror="failed(event.detail)">Delete</button>
```

While a request runs, the element has `aria-busy="true"` and the component's host matches `:state(loading)`:

```css
:host(:state(loading)) .results {
  opacity: 0.5;
}
```

## Built-in safety

- **No stale responses.** A new request from the same element aborts the previous one, so a slow old response never overwrites a newer one. This is what makes search-as-you-type correct without extra code.
- **Shared GETs.** Identical `GET` requests (same URL and headers) in flight at the same time are sent once and shared.
- **Cleanup.** Requests, polls and `visible` observers stop when the element is removed.
- **Sanitised HTML.** `render` removes scripts, event handler attributes and unsafe URLs. See [Security](/docs/security/).

## In the script

For anything the attributes cannot express, use `fetch` with the component's `signal`, so the request is cancelled when the element is removed:

```js
async function exportReport() {
  const response = await fetch("/api/report", { method: "POST", signal });
  report.url = URL.createObjectURL(await response.blob());
}
```


---

# Importing components

Source: http://realm.js.org/docs/importing/

`<import-element>` loads an HTML file and defines every `<custom-element>` in it.

```html
<import-element from="/components/todo-app.html"></import-element>

<todo-app></todo-app>
```

`from` is resolved against the page, like `href`. Elements used before their definition arrives are upgraded when it arrives. Until then, `realm.css` keeps them hidden.

## Behaviour

| Behaviour | What REALM does |
| --- | --- |
| Fetching | Each URL is fetched once. Every `<import-element>` with the same URL, and `importDefinitions(url)`, share that request |
| Bundles | A file can hold any number of `<custom-element>` definitions. All of them are defined |
| Duplicates | Importing the same component twice is harmless. A different definition for a name that already exists keeps the first and warns, naming both files |
| Errors | A failed request fires `error` on the `<import-element>` and logs a warning. The rest of the page keeps working |
| Removal | An `<import-element>` removed before its file arrives stays quiet: it fires no events |
| Throttling | At most six files are fetched at once per origin. The rest wait in a queue |
| Moving | Moving or reinserting an `<import-element>` does not import again |

## Bundles

Group components that are used together in one file. REALM UI ships every component in one `ui.html`:

```html
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/ui.html"></import-element>
```

Smaller bundles load faster, but one file per component makes more requests. A file per feature area is a good default.

## Lazy loading

`loading="lazy"` waits until one of the tags listed in `for` appears in the page (or in any component's markup) before fetching:

```html
<import-element from="/components/charts.html" loading="lazy" for="sales-chart usage-chart"></import-element>
```

Without `for`, a lazy import cannot know what to wait for, so REALM warns.

## Events

`<import-element>` fires `load` when every definition in the file is defined and `error` when the file cannot be loaded:

```html
<import-element
  from="/components/map.html"
  onload="console.info('map ready', event.detail.url)"
  onerror="console.warn('map failed', event.detail.url, event.detail.status)"
></import-element>
```

| Event | `event.detail` |
| --- | --- |
| `load` | `{ url }` |
| `error` | `{ url, status }` (`status` is `0` for network errors) |

## Imports inside component scripts

A component script can import JavaScript modules. Use `<script type="module">` for clarity, and put the imports first:

```html
<custom-element name="cart-badge">
  <script type="module">
    import { cart } from "../state/cart.js";
    import { formatMoney } from "../lib/format.js";

    const badge = useState({
      get total() {
        return formatMoney(cart.total);
      },
    });
  </script>

  <span><slot name="#badge.total"></slot></span>
</custom-element>
```

Relative paths (`./`, `../`) resolve against the component file, not the page, so a component folder can be moved as a whole. Imported names are available to markup and handlers like any top-level name.

## Stylesheets

A definition can link a stylesheet. Its URL also resolves against the component file, and it applies inside the component only:

```html
<custom-element name="fancy-table">
  <link rel="stylesheet" href="./fancy-table.css">
  <table>…</table>
</custom-element>
```

## From JavaScript

`importDefinitions(url)` does the same as `<import-element>` and returns a promise:

```js
import { importDefinitions } from "@realmorg/realm";

await importDefinitions("/components/editor.html");
document.body.append(document.createElement("rich-editor"));
```

## Trust

A component file is code, like a `<script src>`. Importing a component from another origin runs that origin's code in your page. Only import from sources you trust, and pin versions on CDNs.


---

# `on…` handlers

Source: http://realm.js.org/reference/attributes/handlers/

Native-style `on<event>` attributes. Inside component markup they work for **every** event name, native or custom. On a plain page, REALM adds handler attributes and properties for the custom events its components send.

```html
<button onclick="save(item)">Save</button>
<rating-stars onrate="saveRating(event.detail.value)"></rating-stars>
```

## In component markup

The attribute value is JavaScript, compiled together with the component script (no `eval` at event time). It runs as a listener on that element.

| Name | Value |
| --- | --- |
| `event` | The event object |
| `this` | The element the attribute is on |
| Loop variables | The `as` and `index` names of every enclosing `repeat` / `<repeat-list>` |
| Script names | Every top-level name of the component script |
| Helpers | The [script helpers](/reference/script/) (`host`, `dispatch`, `refs`, …) |
| Any other name | Looked up when the handler runs: parent components first, then `globalThis` |

- Returning `false` calls `event.preventDefault()`.
- Listeners are added with the element's [`signal`](/reference/script/signal/) and removed with it.
- [`debounce` and `throttle`](/reference/attributes/debounce-throttle/) on the same element time the handler, except on elements with [fetch attributes](/reference/fetch/fetch/), where they time the request instead.
- A component compiles its handler code once per definition, not per instance.

## On a plain page

Browsers only support handler attributes for native event names. For each REALM component, REALM finds the custom events it sends and adds:

- an `on<name>` **attribute** whose value is JavaScript, compiled when the element connects and recompiled when the attribute changes, and
- an `on<name>` **property** that accepts a function (or `null`) and stays in sync with the attribute.

```html
<rating-stars onrate="console.log(event.detail.value)"></rating-stars>
<script>
  document.querySelector("rating-stars").onrate = (event) => {
    if (event.detail.value < 2) return false;
  };
</script>
```

| Detail | Behaviour |
| --- | --- |
| Event names | Read from the component script: `dispatch("name"`, `new CustomEvent("name"` and `new Event("name"` |
| Native names | Names that already have an `on…` property on `HTMLElement` (`change`, `input`, `toggle`, `close`, …) are left to the browser |
| `this` | The element |
| `return false` | Calls `preventDefault()` |
| Syntax errors | The attribute is ignored |
| Attributes set before the element was defined | Compiled when it connects |

Page handler attributes run in the page scope, so a strict Content Security Policy blocks them like any inline handler.

## Example

```html live
<custom-element name="like-button">
  <script type="realm">
    const likes = useState({ count: 0 });

    function like() {
      likes.count++;
      dispatch("like", { count: likes.count });
    }
  </script>

  <ui-button variant="outline" onclick="like()">Like (<slot name="#likes.count"></slot>)</ui-button>
</custom-element>

<like-button onlike="document.getElementById('like-log').value = 'Liked ' + event.detail.count + ' times'"></like-button>
<output id="like-log">No likes yet.</output>
```

## Related

- [Events](/docs/events/)
- [Component events](/reference/events/component-events/)


---

# `debounce` and `throttle`

Source: http://realm.js.org/reference/attributes/debounce-throttle/

Delay or rate-limit the `on…` handlers of an element, or its request when the element has [fetch attributes](/reference/fetch/fetch/). Used in component markup.

```html
<input oninput="search(this.value)" debounce="300ms">
<div onpointermove="track(event)" throttle="100ms"></div>
<input name="q" fetch="/api/search" trigger="input" debounce="250ms" into="#results.items">
```

## Attributes

| Attribute | Type | Meaning |
| --- | --- | --- |
| `debounce` | [duration](/reference/syntax/#durations) | Run once the events stop for this long, with the last event |
| `throttle` | duration | Run at most once per period, on the leading edge. Events in between are dropped |

If both are present, `debounce` is used.

## What is timed

| Element | Timed |
| --- | --- |
| Element without fetch attributes | Every `on…` handler on it |
| Element with fetch attributes | Requests started by event-name and reference [triggers](/reference/fetch/trigger/). Its own `on…` handlers run immediately. `load`, `visible` and `poll` are not timed |

A pending debounced call is cancelled when the element is removed. An invalid duration logs a warning and counts as `0`.

## Example

```html live
<custom-element name="typing-echo">
  <script type="realm">
    const echo = useState({ text: "", runs: 0 });

    function copy(field) {
      echo.text = field.value;
      echo.runs++;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      width: min(calc(var(--spacing) * 80), 100%);
    }
  </style>

  <input aria-label="Type here" placeholder="Type here" oninput="copy(this)" debounce="500ms">
  <p>Copied 500ms after you stop typing: <slot name="#echo.text"></slot></p>
  <p>Handler runs: <slot name="#echo.runs"></slot></p>
</custom-element>

<typing-echo></typing-echo>
```

## Related

- [Events: debounce and throttle](/docs/events/#debounce-and-throttle)
- [Fetching data](/docs/fetching/)


---

# Stores

Source: http://realm.js.org/docs/stores/

There are two ways to share state:

1. **Parent state** is visible to nested components automatically. See [Nested components and scope](/docs/scope/). This covers most sharing inside one part of a page.
2. **A store** holds app-wide state that several unrelated components use, or that should outlive any one component.

## defineStore

```js
// /state/cart.js
import { defineStore } from "@realmorg/realm";

export const cart = defineStore(
  "cart",
  {
    items: [],
    get count() {
      return this.items.reduce((sum, item) => sum + item.quantity, 0);
    },
  },
  { persist: "local" },
);
```

```html
<custom-element name="cart-badge">
  <script type="module">
    import { cart } from "/state/cart.js";
  </script>

  <ui-badge><slot name="#cart.count">0</slot></ui-badge>
</custom-element>

<custom-element name="add-to-cart">
  <script type="module">
    import { cart } from "/state/cart.js";

    const props = defineProps({ sku: prop.string().required() });

    function add() {
      const line = cart.items.find((item) => item.sku === props.sku);
      if (line) line.quantity++;
      else cart.items.push({ sku: props.sku, quantity: 1 });
    }
  </script>

  <ui-button onclick="add()">Add to cart</ui-button>
</custom-element>
```

- A store is reactive like `useState`, including getters.
- `defineStore` returns the same store for the same name, wherever it is called. Defining it in a module and importing it is the clearest pattern. Calling `defineStore("cart", …)` directly in two component scripts also gives both the same store.
- Nothing is attached to `window`.

`defineStore` is also available inside component scripts without importing, which is handy for small apps:

```html live
<custom-element name="theme-picker">
  <script type="realm">
    const settings = defineStore("docs-demo-settings", { accent: "chart-1" }, { persist: "session" });
    const ACCENTS = ["chart-1", "chart-2", "chart-3", "chart-4", "chart-5"];
    const picker = useState({
      get swatches() {
        return ACCENTS.map((id) => ({ id, color: `var(--${id})`, current: id === settings.accent }));
      },
    });

    function choose(swatch) {
      settings.accent = swatch.id;
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    button {
      width: calc(var(--spacing) * 8);
      height: calc(var(--spacing) * 8);
      border: 2px solid transparent;
      border-radius: var(--radius-full);
      background: var(--swatch);
      cursor: pointer;
    }
    button[aria-pressed="true"] {
      border-color: var(--foreground);
    }
  </style>

  <button type="button" repeat="#picker.swatches" as="swatch" key="id" _aria-label="#swatch.id" _aria-pressed="#swatch.current" _--swatch="#swatch.color" onclick="choose(swatch)"></button>
</custom-element>

<custom-element name="accent-preview">
  <script type="realm">
    const settings = defineStore("docs-demo-settings", { accent: "chart-1" }, { persist: "session" });
    const preview = useState({
      get color() {
        return `var(--${settings.accent})`;
      },
    });
  </script>

  <style type="realm">
    :host {
      display: block;
      padding: calc(var(--spacing) * 3) calc(var(--spacing) * 4);
      border-radius: var(--radius-md);
      background: var(--state-preview-color);
      color: var(--primary-foreground);
      font-weight: var(--font-weight-medium);
    }
  </style>

  Accent: <slot name="#settings.accent"></slot>
</custom-element>

<theme-picker></theme-picker>
<accent-preview></accent-preview>
```

Both components call `defineStore` with the same name, so they share one store. The choice survives a reload in this tab because the store persists to `sessionStorage`.

## Persistence

| `persist` | Where values are saved |
| --- | --- |
| `"local"` | `localStorage`, kept across sessions |
| `"session"` | `sessionStorage`, kept for the tab |
| An adapter | Anything with `get(key)` and `set(key, value)` |

- Values are saved as JSON under the key `realm:<name>` after every change, and restored when the store is defined.
- Types are kept: numbers, booleans, arrays and nested objects come back as they were.
- Getters are never saved or overwritten.
- A stored value that is not valid JSON is ignored with a warning, and the initial values are used.

A custom adapter, for example to namespace keys or add expiry:

```js
const adapter = {
  get: (key) => localStorage.getItem(`myapp:${key}`),
  set: (key, value) => localStorage.setItem(`myapp:${key}`, value),
};

export const prefs = defineStore("prefs", { density: "comfortable" }, { persist: adapter });
```

## Things to know

- A store is defined once per name. Later calls return the existing store and ignore their arguments, so define it in one place.
- Stores are never torn down. Observers you create on a store from inside a component still stop with the component.
- Keep stores for shared data. A value only one component uses belongs in that component's `useState`.


---

# `ref`

Source: http://realm.js.org/reference/attributes/ref/

Names an element in a component's markup. Used in component markup.

```html
<canvas ref="canvas"></canvas>
<div ref="results"></div>
<input ref="control">
```

## Attribute

| Attribute | Type | Meaning |
| --- | --- | --- |
| `ref` | name | Registers the element as `refs[name]` |

## Uses

| Use | How |
| --- | --- |
| Script access | [`refs.name`](/reference/script/refs/) in the script. `refs` is reactive and empty while the script's top level runs. It is filled once the markup is connected, before [`onConnected`](/reference/script/on-connected/) hooks run |
| Render target | [`render="name"`](/reference/fetch/render/) inserts a response into the element with that `ref` |
| Form control | `ref="control"` in a `form-associated` component (see below) |

The attribute stays on the element. When several elements use the same name (for example inside a loop), `refs[name]` is the last one mounted. Content that `<is-visible>` removes is not taken out of `refs`.

## ref="control"

In a component defined with `form-associated`, an `<input>`, `<select>` or `<textarea>` with `ref="control"` becomes the component's delegated control:

| Behaviour | Detail |
| --- | --- |
| Value sync | On `input` and `change`, the control's value is written to the `value` prop (as a number when the prop holds a number), or its `checked` state to the `checked` prop for checkboxes and radios |
| Validity | The control's `validity` and `validationMessage` are mirrored with `internals.setValidity`, anchored to the control |
| `change` | The control's `change` is re-dispatched from the host (bubbling, not composed) |
| Enter | Enter in a text-like control (`text`, `email`, `password`, `number`, `search`, `tel`, `url`, date and time types) submits the outer form |
| Labels | Text of the host's `<label>` elements is copied to the control's `aria-label`, unless it has one |

See [Forms](/docs/forms/#delegating-to-an-inner-control).

## Example

```html live
<custom-element name="focus-field">
  <script type="realm">
    function focusField() {
      refs.field.focus();
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      gap: calc(var(--spacing) * 2);
      align-items: center;
    }
  </style>

  <input ref="field" aria-label="Name" placeholder="Name">
  <ui-button variant="outline" onclick="focusField()">Focus the field</ui-button>
</custom-element>

<focus-field></focus-field>
```

## Related

- [Lifecycle: host, refs and internals](/docs/lifecycle/#host-refs-and-internals)


---

# `repeat`

Source: http://realm.js.org/reference/attributes/repeat/

Repeats the element it is on once per item of an array. It does the same job as [`<repeat-list>`](/reference/elements/repeat-list/) without a wrapper, so it works where the HTML parser only allows certain children: `<ul>`, `<ol>`, `<table>`, `<tbody>`, `<tr>`, `<select>`, `<datalist>`. Used in component markup.

```html
<li repeat="#ref" [as="item"] [index="i"] [key="id"]>…</li>
```

## Attributes

| Attribute | Type | Default | Meaning |
| --- | --- | --- | --- |
| `repeat` | [reference](/reference/syntax/) to an array | required | The list. Anything that is not an array renders nothing |
| `as` | name | `item` | Variable name for the current item |
| `index` | name | none | Variable name for the current position |
| `key` | property name | position | Property that identifies each item between updates |

The four attributes are removed from the copies. Everything else on the element, including `_` bindings and `on…` handlers, is applied to each copy with the loop variables in scope. Keys work as described on [`<repeat-list>`](/reference/elements/repeat-list/#keys).

The original element is replaced by an empty comment that marks where the copies go.

## Example

```html live
<custom-element name="score-table">
  <script type="realm">
    const board = useState({
      rows: [
        { id: "a", name: "Ana", score: 12 },
        { id: "b", name: "Ben", score: 9 },
        { id: "c", name: "Chi", score: 15 },
      ],
    });

    function sort() {
      board.rows.sort((a, b) => b.score - a.score);
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      justify-items: start;
    }
    td,
    th {
      padding: calc(var(--spacing) * 1) calc(var(--spacing) * 3);
      text-align: left;
    }
  </style>

  <table>
    <thead><tr><th>#</th><th>Name</th><th>Score</th></tr></thead>
    <tbody>
      <tr repeat="#board.rows" as="row" index="i" key="id">
        <td><slot name="#i"></slot></td>
        <td><slot name="#row.name"></slot></td>
        <td><slot name="#row.score"></slot></td>
      </tr>
    </tbody>
  </table>
  <ui-button variant="outline" onclick="sort()">Sort by score</ui-button>
</custom-element>

<score-table></score-table>
```

## Related

- [Lists and keys](/docs/lists/)


---

# `focusgroup`

Source: http://realm.js.org/reference/attributes/focusgroup/

Moves focus among the focusable items of a container with the arrow keys, Home and End. REALM implements the arrow-key behaviour of the [Open UI focusgroup proposal](https://open-ui.org/components/scoped-focusgroup.explainer/) in every browser. Used on a container in component markup.

```html
<div role="toolbar" aria-label="Formatting" focusgroup="toolbar inline wrap">…</div>
```

## Tokens

The value is a space-separated list. Tokens other than these are ignored, so the first word can name the widget (`toolbar`, `menu`, `tablist`, `listbox`, `radiogroup`) for readability.

| Token | Effect |
| --- | --- |
| `inline` | Only Left and Right move focus |
| `block` | Only Up and Down move focus |
| neither | All four arrows move focus |
| `wrap` | Moving past the last item goes to the first, and the other way round. Without it, focus stops at the ends |

Left and Right are mirrored when the container's computed `direction` is `rtl`. Home focuses the first item, End the last. Handled keys call `preventDefault()`. The tokens are read on every key press, so changing the attribute takes effect at once.

## Items

Items are found in the flat tree under the container: its children, content slotted into it, and the shadow roots of nested elements.

| Included | Skipped |
| --- | --- |
| `button`, `a[href]`, `input`, `select`, `textarea`, `[tabindex]` | `:disabled`, `[disabled]`, `[aria-disabled="true"]`, `[inert]`, `[hidden]` |
| Custom elements whose shadow root delegates focus (their insides are not searched) | `tabindex="-2"` |
| | Anything not rendered (`checkVisibility()` is false) |

The focusgroup only moves focus. It does not manage `tabindex`. To make the widget one Tab stop, set `tabindex="-1"` on the items that are not current.

## Example

```html live
<custom-element name="align-toolbar">
  <style type="realm">
    div {
      display: inline-flex;
      gap: calc(var(--spacing) * 1);
      padding: calc(var(--spacing) * 1);
      border: 1px solid var(--border);
      border-radius: var(--radius-lg);
    }
  </style>

  <div role="toolbar" aria-label="Alignment" focusgroup="toolbar inline wrap">
    <ui-button variant="ghost" size="sm">Left</ui-button>
    <ui-button variant="ghost" size="sm">Center</ui-button>
    <ui-button variant="ghost" size="sm" disabled>Justify</ui-button>
    <ui-button variant="ghost" size="sm">Right</ui-button>
  </div>
</custom-element>

<align-toolbar></align-toolbar>
```

Click "Left", then use the arrow keys, Home and End. "Justify" is disabled and skipped.

## Related

- [Accessibility: arrow-key navigation](/docs/accessibility/#arrow-key-navigation-with-focusgroup)


---

# `fetch`, `method`, `params` and `headers`

Source: http://realm.js.org/reference/fetch/fetch/

Any element in component markup can send a request with attributes alone. The response goes [into state](/reference/fetch/into/), is [rendered as HTML](/reference/fetch/render/), or is handled in a [`load` event](/reference/events/request-events/).

```html
<button fetch="/api/items" into="#list.items">Load</button>
<form fetch="/api/items" method="post" into="#list.items" into-mode="append">…</form>
<a href="/page/2" render="content">Next</a>
```

## Which elements fetch

| Element | Becomes a fetch element when it has |
| --- | --- |
| Any element | `fetch` |
| `<form>` | `fetch`, or any of `into`, `render`, `busy` (uses `action` and the form's `method`) |
| `<a>` | `fetch`, or any of `into`, `render`, `busy` (uses `href`) |

A fetch `<form>` never submits natively and a fetch `<a>` never navigates. Their `submit` and `click` default actions are always prevented.

## Attributes

| Attribute | Type | Default | Meaning |
| --- | --- | --- | --- |
| `fetch` | URL | form `action`, link `href` | Request URL, resolved against the element's base URL |
| `method` | `get`, `post`, `put`, `patch`, `delete` (any case) | `get` | HTTP method. On a `<form>` this is the form's own `method` attribute |
| `params` | `name:#ref, name:@prop, …` | none | Extra fields read from state when the request is sent |
| `headers` | [reference](/reference/syntax/) to a headers object | none | Request headers (`Record<string, string>`, an array of pairs, or `Headers`) |

A submit button's `formaction` and `formmethod` override the form's URL and method. Other request attributes are [`trigger` and `poll`](/reference/fetch/trigger/), [`debounce` and `throttle`](/reference/attributes/debounce-throttle/), and [`busy` and `timeout`](/reference/fetch/busy-timeout/).

### params

A comma-separated list of `name:reference` pairs. Each value is read when the request is sent. Objects and arrays are sent as JSON text, `null` and `undefined` as `""`.

```html
<button fetch="/api/search" params="q:#search.query, page:#search.page" into="#search.results">Search</button>
```

### headers

```js
const auth = useState({ headers: { Authorization: "Bearer …" } });
```

```html
<button fetch="/api/me" headers="#auth.headers" into="#user.profile">Load profile</button>
```

## What is sent

| Source | Fields |
| --- | --- |
| `<form>` | `new FormData(form, submitter)`, so the clicked submit button's `name` and `value` are included |
| `<input>`, `<select>`, `<textarea>` with a `name` | That one field |
| Any element | The `params` fields, appended last |

| Method | Body |
| --- | --- |
| `GET` | Fields are appended to the URL query string. Identical GET requests (same URL and headers) that are in flight at the same time share one network request |
| Others | `application/x-www-form-urlencoded`, or `multipart/form-data` when the form has `enctype="multipart/form-data"` |

Pending state updates are applied before the request is built, so a handler that changes a field in the same event is seen by the request.

## Response

| Response | Result |
| --- | --- |
| `Content-Type` contains `json` | `data` is the parsed JSON (the text if parsing fails) |
| Anything else | `data` is the text |
| 2xx | `into` and `render` are applied, then `load` fires |
| Other status | `error` fires. `into` and `render` are not applied |

A new request from the same element aborts the previous one (`abort` fires). Removing the element aborts its requests. While any request in a component runs, its host matches [`:state(loading)`](/reference/css/states/#loading), and the element has `aria-busy="true"`.

## Example

```html live
<custom-element name="page-count">
  <script type="realm">
    const site = useState({ pages: [], status: "" });

    function done(event) {
      site.status = `${event.detail.status}, ${site.pages.length} pages`;
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      gap: calc(var(--spacing) * 3);
      align-items: center;
    }
  </style>

  <ui-button fetch="/search-index.json" into="#site.pages" onload="done(event)">Load the search index</ui-button>
  <output><slot name="#site.status">Not loaded</slot></output>
</custom-element>

<page-count></page-count>
```

## Related

- [Fetching data](/docs/fetching/)
- [Request events](/reference/events/request-events/)
- [Security](/docs/security/)


---

# Styling

Source: http://realm.js.org/docs/styling/

A component's `<style>` and `<link rel="stylesheet">` children become constructable stylesheets adopted by its shadow root. They apply inside the component only, and one stylesheet is shared by every instance of the component.

```html
<custom-element name="info-note">
  <style>
    :host {
      display: block;
      padding: calc(var(--spacing) * 4);
      border-radius: var(--radius-lg);
      background: var(--muted);
    }
    :host([hidden]) {
      display: none;
    }
    ::slotted(a) {
      font-weight: var(--font-weight-medium);
    }
  </style>

  <slot></slot>
</custom-element>
```

The usual shadow DOM tools apply:

| Selector | Styles |
| --- | --- |
| `:host` | The element itself. Give it a `display`. Custom elements are `inline` by default |
| `:host([attr])`, `:host(.class)` | The element when it has an attribute or class |
| `::slotted(selector)` | Top-level elements placed into a `<slot>` from outside |
| `::part(name)` (from outside) | Inner elements marked with `part="name"` |
| `:host(:state(name))` | The element when it has a custom state |

Inherited properties (`color`, `font-*`, CSS custom properties) still flow in from the page.

## Shadow DOM and utility CSS

Every component renders into a shadow root, and the page's stylesheets do not reach inside it. That is what stops a component's styles from leaking out and the page's styles from leaking in. It also means utility-class frameworks such as Tailwind CSS, UnoCSS or Bootstrap's utility classes do not work in a component's markup. Their classes live in the page's stylesheet, so this gets no padding and no font size:

```html
<custom-element name="info-note">
  <!-- p-4 and text-sm are defined in the page, not in this shadow root -->
  <div class="p-4 text-sm"><slot></slot></div>
</custom-element>
```

The Tailwind Play CDN script has the same limit: it writes its styles into the document `<head>` only.

What works instead:

- **Inside a component**, write CSS with the [design tokens](#design-tokens): `padding: calc(var(--spacing) * 4)`, `font-size: var(--text-sm)`.
- **In the page**, use any CSS you like, utility classes included. Content you pass into a component's `<slot>` stays in the page, so page classes style it.
- **Across the boundary**, inherited properties and custom properties do flow in. Tokens you set on `:root` reach every component.
- **For REALM UI components**, use their attributes, `::part()` and `:state()`, described in [Styling components from outside](#styling-components-from-outside).

A component can load a compiled utility stylesheet with `<link rel="stylesheet">`, but every component then carries the whole file and you need a build step to generate it. REALM does not recommend it.

## Reactive CSS

REALM reads the component's CSS for two patterns and keeps them in sync with props and state. Nothing needs to be declared in the script.

### Variables: --attr-* and --state-*

`var(--attr-name)` is the value of the prop or attribute `name`. `var(--state-todo-count)` is the value of `#todo.count`, with dots written as dashes. REALM sets these as custom properties on the host, so they work anywhere in the component's styles, including `calc()`:

```html live
<custom-element name="meter-bar">
  <script type="realm">
    const props = defineProps({ value: prop.number().min(0).max(100).default(40), hue: prop.number().default(150) });
    const meter = useState({
      get width() {
        return `${props.value}%`;
      },
    });

    function nudge(amount) {
      props.value = Math.min(100, Math.max(0, props.value + amount));
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      width: calc(var(--spacing) * 72);
    }
    .track {
      height: calc(var(--spacing) * 3);
      border-radius: var(--radius-full);
      background: var(--muted);
    }
    .fill {
      width: var(--state-meter-width);
      height: 100%;
      border-radius: inherit;
      background: oklch(0.65 0.15 var(--attr-hue));
      transition: width var(--default-transition-duration);
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
  </style>

  <div class="track"><div class="fill"></div></div>
  <div class="actions">
    <ui-button size="sm" variant="outline" onclick="nudge(-10)">-10</ui-button>
    <ui-button size="sm" variant="outline" onclick="nudge(10)">+10</ui-button>
  </div>
</custom-element>

<meter-bar></meter-bar>
<meter-bar value="75" hue="30"></meter-bar>
```

Objects, arrays, `null` and `undefined` remove the variable. For a variable on an inner element instead of the host, bind it: `<div _--width="#meter.width">`.

### States: :state(attr-…) and :state(state-…)

`:state(attr-open)` matches while the prop or attribute `open` is truthy. `:state(state-todo-isEmpty)` matches while `#todo.isEmpty` is truthy. Add a comparison to match a specific value:

| Selector | Matches when |
| --- | --- |
| `:state(attr-variant-is-outline)` | `variant` equals `"outline"` |
| `:state(state-cart-count-gt-0)` | `cart.count > 0` |
| `:state(state-cart-count-gte-10)` | `cart.count >= 10` |
| `:state(state-stock-left-lt-5)` | `stock.left < 5` |
| `:state(state-stock-left-lte-0)` | `stock.left <= 0` |

This is how REALM UI styles its variants without any script:

```css
:host(:state(attr-variant-is-destructive)) button {
  background: var(--destructive);
  color: var(--destructive-foreground);
}
:host(:state(attr-size-is-sm)) button {
  height: calc(var(--spacing) * 8);
}
```

```html live
<custom-element name="stock-label">
  <script type="realm">
    const props = defineProps({ left: prop.number().int().min(0).default(0) });
  </script>

  <style type="realm">
    :host {
      display: inline-flex;
      padding: calc(var(--spacing) * 1) calc(var(--spacing) * 3);
      border-radius: var(--radius-full);
      background: var(--secondary);
      font-size: var(--text-sm);
    }
    :host(:state(attr-left-lt-5)) {
      background: color-mix(in oklab, var(--chart-4) 30%, transparent);
    }
    :host(:state(attr-left-lte-0)) {
      background: color-mix(in oklab, var(--destructive) 10%, transparent);
      color: var(--destructive);
    }
  </style>

  <slot name="@left"></slot>&nbsp;left
</custom-element>

<stock-label left="12"></stock-label>
<stock-label left="3"></stock-label>
<stock-label left="0"></stock-label>
```

State names follow the reference path with dashes, so the names in a path should not themselves contain dashes. These states are custom states (`CustomStateSet`), so they are also visible from outside: `ui-button:state(attr-variant-is-outline)`.

### Your own states

Set states from the script with `internals.states`:

```js
observe(() => {
  if (menu.open) internals.states.add("open");
  else internals.states.delete("open");
});
```

REALM adds `:state(loading)` to a component's host while one of its [fetch attributes](/docs/fetching/) is running.

## Design tokens

REALM UI's `theme.css` defines the tokens its components use. Use them in your own components so they match REALM UI and follow theme changes:

| Group | Tokens |
| --- | --- |
| Colour | `--background`, `--foreground`, `--card`, `--popover`, `--primary`, `--secondary`, `--muted`, `--accent`, `--destructive` (each with a `-foreground` pair where it makes sense), `--border`, `--input`, `--ring`, `--chart-1` to `--chart-5`, `--sidebar*` |
| Spacing | `--spacing` (0.25rem). Write sizes as `calc(var(--spacing) * 4)` |
| Type | `--text-xs` to `--text-4xl`, `--font-weight-normal` to `--font-weight-bold`, `--leading-tight`, `--leading-normal`, `--tracking-tight`, `--font-sans`, `--font-mono` |
| Radius | `--radius`, `--radius-xs` to `--radius-2xl`, `--radius-full` |
| Shadow | `--shadow-xs` to `--shadow-lg`, `--focus-ring` |
| Motion | `--default-transition-duration`, `--default-transition-timing-function` |

Custom properties inherit through shadow roots, so a token set on `:root` reaches every component.

## Theming and dark mode

Override tokens on `:root`, or on any element to theme a subtree:

```css
:root {
  --radius: 0.375rem;
  --primary: oklch(0.55 0.2 260);
  --primary-foreground: oklch(0.98 0 0);
}

.marketing {
  --font-sans: "Inter", system-ui, sans-serif;
}
```

`theme.css` switches to dark colours when the system prefers a dark scheme, unless the page sets `data-theme="light"` on `<html>`. Setting `data-theme="dark"` forces dark mode. A theme toggle sets that attribute:

```js
document.documentElement.dataset.theme = "dark";
```

## Styling components from outside

Shadow styles are encapsulated, so page CSS cannot reach inside a component by accident. Components choose what to expose:

- `part="name"` on inner elements, styled from outside with `ui-dialog::part(dialog)`,
- CSS custom properties they read, such as tokens,
- custom states, styled with `ui-button:state(attr-variant-is-ghost)`.

Each REALM UI component page lists its parts and states.


---

# `trigger` and `poll`

Source: http://realm.js.org/reference/fetch/trigger/

Decide when a [fetch element](/reference/fetch/fetch/) sends its request.

```html
<div fetch="/api/stats" trigger="load visible" into="#stats.data"></div>
<input name="q" fetch="/api/search" trigger="input" debounce="250ms" into="#search.results">
<section fetch="/api/items" trigger="#filters.category, @user" into="#list.items"></section>
<div fetch="/api/feed" trigger="load" poll="30s" into="#feed.items"></div>
```

## trigger

A list of triggers separated by spaces or commas. Each one sends the request:

| Trigger | Sends when | Timed by `debounce`/`throttle` |
| --- | --- | --- |
| an event name (`click`, `input`, `mouseenter`, `my-event`, …) | That event fires on the element | yes |
| `load` | Once, right after the element is set up | no |
| `visible` | The element enters the viewport (`IntersectionObserver`), each time it does | no |
| `#state.path`, `@prop` | The referenced value changes (compared as JSON). Not on the first read | yes |

Default when `trigger` is absent:

| Element | Default trigger |
| --- | --- |
| `<form>` | `submit` |
| `<input>`, `<select>`, `<textarea>` | `change` |
| anything else | `click` |

Setting `trigger` replaces the default, so `<form trigger="input">` no longer sends on submit (and still never submits natively).

## poll

| Attribute | Type | Meaning |
| --- | --- | --- |
| `poll` | [duration](/reference/syntax/#durations) | Also send the request every period, until the element is removed. Not timed by `debounce`/`throttle` |

`poll` does not send immediately. Combine it with `trigger="load"` to load first and then refresh.

## Example

```html live
<custom-element name="section-filter">
  <script type="realm">
    const filter = useState({ section: "Docs", pages: [] });
    const view = useState({
      get matches() {
        return filter.pages.filter((page) => page.section === filter.section).length;
      },
    });
  </script>

  <style type="realm">
    :host {
      display: flex;
      flex-wrap: wrap;
      gap: calc(var(--spacing) * 2);
      align-items: center;
    }
  </style>

  <select aria-label="Section" onchange="filter.section = this.value">
    <option>Docs</option>
    <option>Components</option>
    <option>Reference</option>
  </select>
  <span fetch="/search-index.json" trigger="load, #filter.section" into="#filter.pages"></span>
  <output><slot name="#view.matches"></slot> pages in <slot name="#filter.section"></slot></output>
</custom-element>

<section-filter></section-filter>
```

The request runs on load and again whenever `#filter.section` changes.

## Related

- [Fetching data: refetching when state changes](/docs/fetching/#refetching-when-state-changes)


---

# `into`, `into-mode` and `into-key`

Source: http://realm.js.org/reference/fetch/into/

Write a successful response's `data` into state. `data` is the parsed JSON when the response is JSON, otherwise the text.

```html
<button fetch="/api/items" into="#list.items">Load</button>
<form fetch="/api/items" method="post" into="#list.items" into-mode="append">…</form>
<button fetch="/api/items/3" method="delete" into="#list.items" into-mode="remove">Delete</button>
```

## Attributes

| Attribute | Type | Default | Meaning |
| --- | --- | --- | --- |
| `into` | writable [reference](/reference/syntax/) | none | Where to write. Needs at least one property (`#list.items`), cannot be a prop or negated |
| `into-mode` | `replace`, `append`, `prepend`, `update`, `remove` | `replace` | How `data` is combined with the current value |
| `into-key` | property name | `id` | Identity property for `update` and `remove` |

`into` is applied before `render` and before the `load` event. It is not applied for non-2xx responses.

## Modes

For every mode except `replace`, the current value is treated as a list (`[]` if it is not an array) and `data` as a list of items (a single value becomes one item).

| Mode | New value |
| --- | --- |
| `replace` | `data` |
| `append` | current items, then the new items |
| `prepend` | the new items, then current items |
| `update` | Each current item whose `into-key` matches a new item is replaced by it, in place. New items with no match are appended |
| `remove` | Current items whose `into-key` matches a new item are removed |

An unknown `into-mode` behaves like `append`. The write replaces the array, so a `key` on the list keeps unchanged rows.

## Example

```html live
<custom-element name="first-pages">
  <script type="realm">
    const list = useState({ pages: [] });
    const view = useState({
      get count() {
        return list.pages.length;
      },
    });
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      justify-items: start;
    }
    div {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
  </style>

  <div>
    <ui-button fetch="/search-index.json" into="#list.pages">Replace</ui-button>
    <ui-button variant="outline" fetch="/search-index.json" into="#list.pages" into-mode="append">Append</ui-button>
    <ui-button variant="outline" fetch="/search-index.json" into="#list.pages" into-mode="update" into-key="url">Update by url</ui-button>
  </div>
  <p><slot name="#view.count"></slot> items in the list</p>
</custom-element>

<first-pages></first-pages>
```

"Append" doubles the list each time. "Update by url" replaces matching pages in place, so the count stays the same.

## Related

- [Fetching data: updating one item in a list](/docs/fetching/#updating-one-item-in-a-list)


---

# `render`, `render-mode` and `render-select`

Source: http://realm.js.org/reference/fetch/render/

Insert a successful response into an element named with [`ref`](/reference/attributes/ref/). The response text is parsed as HTML and sanitised first.

```html
<a href="/articles/2" render="article">Next article</a>
<article ref="article"></article>

<button fetch="/fragments/comments" render="comments" render-mode="append" render-select=".comment">More</button>
<div ref="comments"></div>
```

## Attributes

| Attribute | Type | Default | Meaning |
| --- | --- | --- | --- |
| `render` | a `ref` name in the same component | none | The target. If no element has that ref, REALM warns |
| `render-mode` | see below | `replace` | Where the HTML goes |
| `render-select` | CSS selector | none | Keep only the elements of the response that match |

## Modes

| `render-mode` | Effect on the target |
| --- | --- |
| `replace` | Replaces its children |
| `outer` | Replaces the target itself |
| `append` | Adds after its last child |
| `prepend` | Adds before its first child |
| `before` | Inserts before the target |
| `after` | Inserts after the target |
| `merge` | Updates its children in place: matching nodes keep their identity, attributes and text are patched, extra nodes are removed, new ones appended. A focused element is left alone |
| `text` | Sets `textContent` to the raw response text (not parsed) |
| `remove` | Removes the target. The response body is ignored |

An unknown mode warns and uses `replace`.

## Sanitising

The parsed HTML has `<script>`, `<style>`, `<iframe>`, `<frame>`, `<frameset>`, `<object>`, `<embed>`, `<link>`, `<meta>`, `<base>`, `<template>` and `<noscript>` removed, along with every `on*` attribute, `srcdoc`, and `javascript:`, `vbscript:` and `data:text/html` URLs. Inserted HTML is not scanned for REALM references, bindings or handlers. Custom elements in it upgrade as usual.

## Links

When an `<a>` with `render` loads, the address bar is updated with `history.pushState` to the request URL.

## Example

```html live
<custom-element name="fragment-loader">
  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: start;
      width: min(calc(var(--spacing) * 120), 100%);
    }
    .target {
      justify-self: stretch;
      min-height: calc(var(--spacing) * 10);
      padding: calc(var(--spacing) * 3);
      border: 1px dashed var(--border);
      border-radius: var(--radius-md);
    }
  </style>

  <ui-button fetch="/404.html" render="target" render-select=".not-found h1" render-mode="append">Append the 404 heading</ui-button>
  <div class="target" ref="target"></div>
</custom-element>

<fragment-loader></fragment-loader>
```

## Related

- [Fetching data: rendering HTML](/docs/fetching/#rendering-html)
- [Security](/docs/security/)


---

# `busy` and `timeout`

Source: http://realm.js.org/reference/fetch/busy-timeout/

Track a [fetch element](/reference/fetch/fetch/)'s request and set a time limit for it.

```html
<form fetch="/api/save" method="post" busy="#form.saving" timeout="10s">
  <ui-button type="submit" _disabled="#form.saving">Save</ui-button>
</form>
```

## Attributes

| Attribute | Type | Default | Meaning |
| --- | --- | --- | --- |
| `busy` | writable [reference](/reference/syntax/) | none | Set to `true` when a request starts and `false` when the latest one ends |
| `timeout` | [duration](/reference/syntax/#durations) | none | Abort the request after this long and fire `timeout` instead of `abort` |

## While a request runs

| What | Value |
| --- | --- |
| `busy` reference | `true` |
| `aria-busy` on the element | `"true"`, removed afterwards (with or without `busy`) |
| [`:state(loading)`](/reference/css/states/#loading) on the component host | Present while any request in the component runs |

When a newer request replaces a running one, `busy` stays `true` until the newer one ends.

## Example

```html live
<custom-element name="slow-save">
  <script type="realm">
    const form = useState({ saving: false, result: "" });
  </script>

  <style type="realm">
    :host {
      display: flex;
      gap: calc(var(--spacing) * 3);
      align-items: center;
    }
    :host(:state(loading)) output {
      color: var(--muted-foreground);
    }
  </style>

  <ui-button fetch="/search-index.json" busy="#form.saving" timeout="5s" _disabled="#form.saving" onload="form.result = 'Done'">Load</ui-button>
  <output><is-visible when="#form.saving">Loading…</is-visible><slot name="#form.result"></slot></output>
</custom-element>

<slow-save></slow-save>
```

## Related

- [Request events: timeout](/reference/events/request-events/)
- [Fetching data](/docs/fetching/)


---

# Component script

Source: http://realm.js.org/reference/script/

The first `<script>` inside a [`<custom-element>`](/reference/elements/custom-element/) is the component script. It is plain JavaScript in strict mode.

```html
<custom-element name="todo-app">
  <script type="realm">
    const props = defineProps({ title: prop.string().default("Todo") });
    const todo = useState({ items: [], draft: "" });

    function add() {
      todo.items.push({ id: crypto.randomUUID(), title: todo.draft });
      todo.draft = "";
    }

    observe(() => {
      document.title = `${todo.items.length} · ${props.title}`;
    });
  </script>
  …
</custom-element>
```

## How it runs

- Once per element, when the element is first connected, before its markup is created.
- Top-level `const`, `let`, `var`, `function` and `class` declarations (including destructured names) and imported names are **exposed**: markup reads them with `#name.path` and handlers call them by name.
- `refs` is empty while the top level runs. Use [`onConnected`](/reference/script/on-connected/) or [`observe`](/reference/script/observe/) for work that needs the markup.
- Leading `import` statements are hoisted and the script runs as a module. Relative specifiers resolve against the file that holds the definition.
- An error thrown at the top level is logged, and the markup still renders.

## Helpers in scope

These names are available without importing. They are not exposed to markup unless you assign them to a top-level name.

| Group | Helpers |
| --- | --- |
| Props and state | [`defineProps`](/reference/script/define-props/), [`prop`](/reference/script/prop/), [`useState`](/reference/script/use-state/), [`observe`](/reference/script/observe/), [`tick`](/reference/script/tick/), [`defineStore`](/reference/script/define-store/) |
| Element | [`host`](/reference/script/host/), [`refs`](/reference/script/refs/), [`signal`](/reference/script/signal/), [`internals`](/reference/script/internals/), [`attrs`](/reference/script/attrs/), [`useChildren`](/reference/script/use-children/), [`defineMethods`](/reference/script/define-methods/), [`dispatch`](/reference/script/dispatch/), [`listen`](/reference/script/listen/), [`lookup`](/reference/script/lookup/) |
| Timers | [`setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`](/reference/script/timers/) |
| Lifecycle | [`onConnected`](/reference/script/on-connected/), [`onDisconnected`](/reference/script/on-disconnected/), [`onFormReset`](/reference/script/on-form-reset/), [`onFormDisabled`](/reference/script/on-form-disabled/), [`onFormStateRestore`](/reference/script/on-form-state-restore/) |

## Signatures

```ts
defineProps<T extends Record<string, PropType>>(schema: T): Record<keyof T, unknown>
useState<T extends object>(initial: T): T
observe(fn: () => unknown): () => void
tick(): Promise<void>
defineStore<T extends object>(name: string, initial: T, options?: StoreOptions): T
useChildren(selector: string, attributes?: string[]): Element[]
defineMethods(methods: object): void
dispatch(type: string, detail?: unknown, options?: CustomEventInit): boolean
listen(type: string, handler: (event: Event) => unknown, target?: EventTarget): void
lookup(name: string): unknown
onConnected(fn: () => unknown): void
onDisconnected(fn: () => void): void
onFormReset(fn: () => void): void
onFormDisabled(fn: (disabled: boolean) => void): void
onFormStateRestore(fn: (state: unknown, mode: string) => void): void
setTimeout(callback: (...args: unknown[]) => void, delay?: number, ...args: unknown[]): number
setInterval(callback: (...args: unknown[]) => void, delay?: number, ...args: unknown[]): number
clearTimeout(id?: number): void
clearInterval(id?: number): void

attrs: Record<string, string | null>
host: HTMLElement
refs: Record<string, Element>
signal: AbortSignal
internals: ElementInternals
prop: { string, number, boolean, enum, date, array, object }
```

The `Context` type exported by `@realmorg/realm` describes this object.

## Order

Write scripts in this order, so they read the same way across components:

1. `defineProps`
2. `useState` (and `defineStore`)
3. functions
4. `defineMethods`, `listen`, lifecycle hooks
5. `observe`

## Related

- [Component anatomy: helpers available in the script](/docs/components/#helpers-available-in-the-script)
- [Nested components and scope](/docs/scope/)


---

# Forms

Source: http://realm.js.org/docs/forms/

Add `form-associated` to a definition and the component becomes a form field through `ElementInternals`. It takes part in submission and `FormData`, `form.reset()`, `<fieldset disabled>`, validation, labels and back/forward restore, like `<input>`.

```html
<custom-element name="star-input" form-associated>
  …
</custom-element>

<form>
  <star-input name="rating" required></star-input>
</form>
```

The `name` attribute works as on native fields, because the browser reads it from the element.

## Values are synced for you

If a form-associated component declares a prop called `value`, REALM keeps the submitted form value equal to it. If it declares `checked`, the field submits its `value` (or `"on"`) only while `checked` is true, like a checkbox.

On `form.reset()`, every prop is parsed again from its attribute, so the field returns to the value written in the HTML. When the browser restores form state (back/forward navigation or autofill), `value` or `checked` is restored.

## Delegating to an inner control

Most fields wrap a native control. Mark it with `ref="control"` and REALM wires it up:

- typing in the control updates the `value` prop (as a number when the prop is a number), and toggling a checkbox or radio updates `checked`,
- the control's validity (`required`, `pattern`, `min`, `type="email"`, …) becomes the component's validity, so `form.checkValidity()` and `:invalid` work,
- `change` from the control is re-dispatched from the host,
- pressing Enter in a text-like control submits the form, like a native input,
- a `<label>` around the component, or one pointing at it, names the inner control.

```html live
<custom-element name="quantity-input" form-associated delegates-focus>
  <script type="realm">
    const props = defineProps({
      value: prop.number().int().default(1),
      min: prop.number().default(1),
      max: prop.number().default(10),
      disabled: prop.boolean(),
    });

    function step(amount) {
      props.value = Math.min(props.max, Math.max(props.min, props.value + amount));
    }
  </script>

  <style type="realm">
    :host {
      display: inline-flex;
      align-items: center;
      gap: calc(var(--spacing) * 1);
    }
    input {
      width: calc(var(--spacing) * 14);
      height: calc(var(--spacing) * 8);
      border: 1px solid var(--input);
      border-radius: var(--radius-md);
      background: transparent;
      color: inherit;
      font: inherit;
      text-align: center;
    }
    input:invalid {
      border-color: var(--destructive);
    }
  </style>

  <ui-button size="icon-sm" variant="outline" aria-label="Less" _disabled="@disabled" onclick="step(-1)">-</ui-button>
  <input ref="control" type="number" _value="@value" _min="@min" _max="@max" _disabled="@disabled">
  <ui-button size="icon-sm" variant="outline" aria-label="More" _disabled="@disabled" onclick="step(1)">+</ui-button>
</custom-element>

<custom-element name="order-form">
  <script type="realm">
    const result = useState({ text: "Submit to see the form data." });

    function submit(event) {
      event.preventDefault();
      result.text = new URLSearchParams(new FormData(event.target)).toString();
    }

    function cleared() {
      result.text = "Reset.";
    }
  </script>

  <style type="realm">
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: start;
    }
    label {
      display: flex;
      gap: calc(var(--spacing) * 3);
      align-items: center;
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      font-family: var(--font-mono);
      font-size: var(--text-sm);
    }
  </style>

  <form onsubmit="submit(event)" onreset="cleared()">
    <label>Coffee <quantity-input name="coffee" value="2"></quantity-input></label>
    <label>Tea <quantity-input name="tea" value="1" max="3"></quantity-input></label>
    <label>Cake (sold out) <quantity-input name="cake" disabled></quantity-input></label>
    <div class="actions">
      <ui-button type="submit">Order</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
    <output><slot name="#result.text"></slot></output>
  </form>
</custom-element>

<order-form></order-form>
```

In the demo:

- `coffee` and `tea` are submitted. `cake` is not, because it is disabled. Its inner buttons and input follow `props.disabled`.
- Typing a number above `max` makes the field invalid, and submitting is blocked by native validation.
- Reset puts every field back to its `value` attribute.

## Disabled fields

Inside a form-associated component, `props.disabled` is `true` when the `disabled` attribute is set **or** when a surrounding `<fieldset disabled>` disables the field. Bind it to inner controls (`_disabled="@disabled"`) and both cases work.

## Doing it by hand

Without a `value` or `checked` prop, or for anything special, use `internals` directly:

```js
const props = defineProps({ tags: prop.array(prop.string()).default([]), required: prop.boolean() });

observe(() => {
  internals.setFormValue(props.tags.join(","));
  internals.setValidity(
    props.required && props.tags.length === 0 ? { valueMissing: true } : {},
    "Add at least one tag.",
  );
});
```

`internals.form`, `internals.labels`, `internals.validity` and `internals.willValidate` are the native properties.

## Form lifecycle hooks

| Hook | Runs when |
| --- | --- |
| `onFormReset(fn)` | The form is reset. Runs after REALM re-reads the props |
| `onFormDisabled(fn)` | The field becomes disabled or enabled through a fieldset or its own attribute. `fn(disabled)` |
| `onFormStateRestore(fn)` | The browser restores the field's state. `fn(state, mode)`, where `mode` is `"restore"` or `"autocomplete"` |

## Submitting with fetch attributes

A `<form>` with [fetch attributes](/docs/fetching/) sends its fields, including form-associated components, without a page load:

```html
<form action="/api/orders" method="post" into="#orders.list" into-mode="append" onload="this.reset()">
  <quantity-input name="coffee" value="1"></quantity-input>
  <ui-button type="submit">Order</ui-button>
</form>
```

## REALM UI fields

Every REALM UI input is form-associated: [Input](/components/input/), [Textarea](/components/textarea/), [Select](/components/select/), [Checkbox](/components/checkbox/), [Switch](/components/switch/), [Radio Group](/components/radio-group/), [Slider](/components/slider/), [Input OTP](/components/input-otp/), [Combobox](/components/combobox/), [Calendar](/components/calendar/), [Toggle](/components/toggle/), [Toggle Group](/components/toggle-group/), and [Button](/components/button/) for submit and reset.


---

# Accessibility

Source: http://realm.js.org/docs/accessibility/

REALM components are native elements with shadow roots, so the usual rules apply: use native `<button>`, `<a>`, `<input>` and `<dialog>` elements inside, keep a logical focus order, and expose state with ARIA. REALM adds the helpers below.

## Default roles

`role` on the definition gives every instance a default role through `ElementInternals`. Pages can still override it with a `role` attribute on the element.

```html
<custom-element name="status-pill" role="status">
  <slot></slot>
</custom-element>
```

Because the role lives in `ElementInternals`, it does not appear as an attribute. Some testing tools, including older versions of axe-core, do not read it.

## Delegating focus

`delegates-focus` on the definition creates the shadow root with `delegatesFocus: true`. Focusing the host, clicking it, or pointing a `<label>` at it moves focus to the first focusable element inside, and the host matches `:focus`:

```html
<custom-element name="search-box" delegates-focus>
  <input type="search" aria-label="Search">
</custom-element>
```

Every REALM UI control that wraps a native control delegates focus.

## Arrow-key navigation with focusgroup

Toolbars, menus, tab lists and radio groups move focus with the arrow keys instead of Tab. Add a `focusgroup` attribute to the container in a component's markup:

```html
<div role="toolbar" aria-label="Formatting" focusgroup="toolbar inline wrap">
  <button>Bold</button>
  <button>Italic</button>
  <button>Underline</button>
</div>
```

REALM implements the arrow-key behaviour of the [Open UI focusgroup proposal](https://open-ui.org/components/scoped-focusgroup.explainer/) in every browser, including those without native support:

| Token | Effect |
| --- | --- |
| `inline` | Only Left and Right arrows move focus (mirrored in right-to-left text) |
| `block` | Only Up and Down arrows move focus |
| neither | All four arrows move focus |
| `wrap` | Moving past the last item goes to the first, and the other way round |

Home and End move to the first and last item. Items are the focusable descendants (buttons, links with `href`, form controls, elements with `tabindex`, and custom elements that delegate focus), including content slotted in from outside. Disabled, `hidden`, `inert` and `aria-disabled="true"` items are skipped, and so is anything with `tabindex="-2"`. The first token describes the widget (`toolbar`, `menu`, `tablist`, `listbox`, …) and is there for readability.

```html live
<custom-element name="text-toolbar">
  <style type="realm">
    div {
      display: inline-flex;
      gap: calc(var(--spacing) * 1);
      padding: calc(var(--spacing) * 1);
      border: 1px solid var(--border);
      border-radius: var(--radius-lg);
    }
  </style>

  <div role="toolbar" aria-label="Formatting" focusgroup="toolbar inline wrap">
    <ui-toggle aria-label="Bold"><b>B</b></ui-toggle>
    <ui-toggle aria-label="Italic"><i>I</i></ui-toggle>
    <ui-toggle aria-label="Underline"><u>U</u></ui-toggle>
  </div>
</custom-element>

<text-toolbar></text-toolbar>
```

Click the first button, then use the Left and Right arrows, Home and End.

The focusgroup moves focus. It does not manage `tabindex`. When a widget should be a single Tab stop, set `tabindex="-1"` on the items that are not current, as REALM UI's tabs and calendar do.

## ARIA state from data

Bind ARIA attributes like any other attribute. Booleans become `"true"` and `"false"`, which is what ARIA expects:

```html
<button _aria-expanded="#menu.open" aria-controls="menu" onclick="toggle()">Menu</button>
<li repeat="#list.items" as="item" key="id" role="option" _aria-selected="#item.selected">…</li>
<section _aria-busy="#feed.loading">…</section>
```

Elements with [fetch attributes](/docs/fetching/) get `aria-busy="true"` automatically while their request runs.

## Labelling form fields

For [form-associated](/docs/forms/) components that delegate to an inner control with `ref="control"`, a native `<label>` around the component, or one whose `for` points at it, names the inner control. Without a label, pass `aria-label` through to the control with a prop:

```js
defineProps({ label: prop.string().attribute("aria-label") });
```

```html
<input ref="control" _aria-label="@label">
```

## Content that appears and disappears

`<is-visible>` and `<is-hidden>` remove content from the DOM, so assistive technology does not see hidden content. When content changes in place and users should hear it, put it in a live region (`role="status"` or `aria-live="polite"`) that stays in the DOM.

## Checklist for your own components

- Use native interactive elements inside. Never make a `<div>` clickable.
- Give icon-only buttons an accessible name.
- Show focus: style `:focus-visible` (REALM UI uses `box-shadow: var(--focus-ring)`).
- Respect `prefers-reduced-motion` for animations.
- Test with the keyboard only, and with a screen reader.

Each REALM UI component page lists its roles and keyboard support.


---

# `defineProps`

Source: http://realm.js.org/reference/script/define-props/

Declares the component's props and returns a reactive object of their current values.

```ts
defineProps<T extends Record<string, PropType>>(schema: T): Record<keyof T, unknown>
```

```js
const props = defineProps({
  label: prop.string().required(),
  size: prop.enum(["sm", "md", "lg"]).default("md"),
  count: prop.number().int().min(0).default(0).reflect(),
  disabled: prop.boolean(),
});
```

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `schema` | object of [`prop`](/reference/script/prop/) types | One key per prop |

Returns a reactive object. Read it in observers, getters and handlers. Reference it from markup with `@name`.

## Attributes and properties

| For each key | Behaviour |
| --- | --- |
| Attribute | camelCase keys map to kebab-case attributes (`maxItems` → `max-items`), or the name given with `.attribute()` |
| Property | Defined on the element (`element.maxItems`). Reading gives the current value. Writing validates it |
| Attribute changes | Parsed with the type's rules (see [`prop`](/reference/script/prop/)) and validated |
| Properties set before upgrade | A value assigned to the property before the element was defined is kept and validated |
| Invalid value | Logs `prop "name" … Using the default.` and uses the default (`false` for booleans, otherwise `undefined` unless `.default()` is set) |
| `.reflect()` | Property writes also update the attribute |
| Teardown | The property accessors are removed when the element is removed |

## Writing props from inside

Writing a declared key on the returned object goes through the property setter. The value is validated, and reflected if the type has `.reflect()`. Writing an undeclared key logs `"name" is not a declared prop.` and does nothing.

```js
function increment() {
  props.count++;
}
```

## Form-associated components

In a component defined with `form-associated`:

| Prop | Extra behaviour |
| --- | --- |
| `disabled` | Reads `true` while a surrounding `<fieldset disabled>` disables the element, even if the prop is `false` |
| `value` | Becomes the form value (`String(value)`, or no value when `null`/`undefined`) |
| `checked` | When declared, the form value is `value` (or `"on"`) while `checked`, and nothing while unchecked |
| all | Re-parsed from attributes on form reset. `value` or `checked` is restored on back/forward navigation |

## Rules

- Call it at most once per script. A second call throws `<tag> called defineProps more than once.`
- Props appear in CSS as [`var(--attr-name)`](/reference/css/variables/) and [`:state(attr-name)`](/reference/css/states/).

## Example

```html live
<custom-element name="price-tag">
  <script type="realm">
    const props = defineProps({
      amount: prop.number().min(0).default(0),
      currency: prop.enum(["USD", "EUR", "JPY"]).default("USD"),
    });

    const price = useState({
      get text() {
        return new Intl.NumberFormat("en", { style: "currency", currency: props.currency }).format(props.amount);
      },
    });
  </script>

  <strong><slot name="#price.text"></slot></strong>
</custom-element>

<p><price-tag amount="19.5"></price-tag> · <price-tag amount="1200" currency="JPY"></price-tag> · <price-tag amount="7" currency="EUR"></price-tag></p>
```

## Related

- [Props](/docs/props/)
- [`prop`](/reference/script/prop/)


---

# `prop`

Source: http://realm.js.org/reference/script/prop/

Builds the prop types passed to [`defineProps`](/reference/script/define-props/). Available in every script, and exported from `@realmorg/realm`.

```js
prop.string().min(2).max(40).required()
prop.number().int().min(0).default(1).reflect()
prop.enum(["sm", "md", "lg"]).default("md")
prop.array(prop.object({ id: prop.number(), label: prop.string() })).default([])
```

Every method returns a **new** type, so types can be stored and reused.

## Types

| Builder | Value type | Attribute text → value |
| --- | --- | --- |
| `prop.string()` | `string` | As is |
| `prop.number()` | `number` | `Number(text)`. Empty or blank text is invalid, and so is `NaN` |
| `prop.boolean()` | `boolean` | Present (any text, even `"false"`) is `true`, absent is `false` |
| `prop.enum(values: string[])` | one of `values` | As is, then checked against `values` |
| `prop.date()` | `Date` | `new Date(text)`. An invalid date is invalid |
| `prop.array(item?: PropType)` | `unknown[]` | `JSON.parse(text)`. Every item is checked with `item` when given |
| `prop.object(shape?: Record<string, PropType>)` | plain object | `JSON.parse(text)`. Each key in `shape` is checked with its type |

Property writes skip the text conversion and are checked directly, so `element.count = "3"` is invalid for a number prop.

## Rules

| Rule | Applies to | Meaning | Failure message |
| --- | --- | --- | --- |
| `.default(value)` | all | Value when the prop is missing, `null`, `undefined` or invalid. Objects and arrays are cloned for each element | |
| `.required()` | all | Missing values are invalid (unless there is a default) | `is required` |
| `.optional()` | all | Undoes `.required()`. Missing values are `undefined` (`false` for booleans) | |
| `.reflect()` | all | Property writes update the attribute | |
| `.attribute(name)` | all | Use this attribute name instead of the kebab-case key | |
| `.min(n)` | string, number | Minimum length, or minimum value | `must be at least n characters` / `must be at least n` |
| `.max(n)` | string, number | Maximum length, or maximum value | `must be at most n characters` / `must be at most n` |
| `.int()` | number | Must be an integer | `must be an integer` |
| `.pattern(regex)` | string | Must match `regex` | `must match /…/` |
| `.email()` | string | Must look like `name@host.tld` | `must be an email address` |
| `.url()` | string | Must be parseable by `URL.canParse` | `must be a URL` |

Type mismatches report `expected a string, got number`, `"NaN" is not a number`, `must be one of "sm", "md", "lg"`, `is not a valid date`, `expected an array`, `expected an object`, or `"…" is not valid JSON`. Nested failures name the position: `[2] expected a string`, `.label is required`.

## Reflection

With `.reflect()`, writing the property writes the attribute:

| Value | Attribute |
| --- | --- |
| `true` | present, empty |
| `false`, `null`, `undefined` | removed |
| `Date` | `toISOString()` |
| object or array | `JSON.stringify(value)` |
| anything else | `String(value)` |

## Example

```html live
<custom-element name="rating-badge">
  <script type="realm">
    const props = defineProps({
      score: prop.number().min(0).max(5).default(0),
      label: prop.string().max(12).default("Rating"),
    });
  </script>

  <ui-badge variant="secondary"><slot name="@label"></slot>: <slot name="@score"></slot> / 5</ui-badge>
</custom-element>

<rating-badge score="4"></rating-badge>
<rating-badge score="9" label="Score out of range"></rating-badge>
```

The second badge's `score` fails `.max(5)` and its label fails `.max(12)`, so both use their defaults (a warning is logged for each).

## Related

- [Props: types and modifiers](/docs/props/#types)


---

# `useState`

Source: http://realm.js.org/reference/script/use-state/

Returns a deep reactive proxy of a plain object or array. Also exported from `@realmorg/realm` for use outside components.

```ts
useState<T extends object>(initial: T): T
```

```js
const todo = useState({
  items: [],
  filter: "all",
  get remaining() {
    return this.items.filter((item) => !item.done).length;
  },
});
```

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `initial` | plain object or array | The object to track. It is not copied: the proxy reads and writes it |

Returns the proxy. Write to it directly: `todo.filter = "done"`, `todo.items.push(item)`.

## What is tracked

| Operation | Tracked |
| --- | --- |
| Reading and writing properties | yes, per property |
| Adding and deleting keys, `in`, `Object.keys`, `for…in` | yes |
| Nested plain objects and arrays | yes, wrapped lazily when read |
| Array index writes, `length`, `push`, `pop`, `shift`, `unshift`, `splice`, `sort`, `reverse`, `fill`, `copyWithin` | yes |
| `includes`, `indexOf`, `lastIndexOf` | yes, and they find both raw and proxied members |
| `Map`, `Set`, `Date`, class instances | no. They are returned unchanged |

Writing the same value (`Object.is`) does not notify.

## Getters and setters

- A getter is a **cached derived value**. It recomputes only after something it read changes, and only when read again.
- A setter runs with the proxy as `this`, so writes inside it are tracked.
- A getter that throws reports the error to whoever reads it, and recovers on the next change.

## Identity

- The same object always gives the same proxy. `useState(useState(x))` returns the proxy unchanged.
- [`toRaw(proxy)`](/reference/javascript/to-raw/) returns the original object.

## Batching

Changes are collected and applied once per microtask, so several writes in a handler cause one update. [`tick()`](/reference/script/tick/) waits for that update. [`flush()`](/reference/javascript/flush/) applies it synchronously.

## Example

```html live
<custom-element name="todo-mini">
  <script type="realm">
    const todo = useState({
      draft: "",
      items: [{ id: 1, title: "Read the reference", done: true }],
      get remaining() {
        return this.items.filter((item) => !item.done).length;
      },
    });

    function add() {
      if (!todo.draft.trim()) return;
      todo.items.push({ id: Date.now(), title: todo.draft, done: false });
      todo.draft = "";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      width: min(calc(var(--spacing) * 100), 100%);
    }
    form {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    label {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
  </style>

  <form onsubmit="add(); return false">
    <input aria-label="New task" _value="#todo.draft" oninput="todo.draft = this.value">
    <ui-button type="submit">Add</ui-button>
  </form>
  <div>
    <label repeat="#todo.items" as="item" key="id">
      <input type="checkbox" _checked="#item.done" onchange="item.done = this.checked">
      <slot name="#item.title"></slot>
    </label>
  </div>
  <p><slot name="#todo.remaining"></slot> remaining</p>
</custom-element>

<todo-mini></todo-mini>
```

## Related

- [State and reactivity](/docs/state/)
- [`observe`](/reference/script/observe/)


---

# `observe`

Source: http://realm.js.org/reference/script/observe/

Runs a function now and again whenever a reactive value it read changes.

```ts
observe(fn: () => unknown): () => void
```

```js
observe(() => {
  localStorage.setItem("draft", todo.draft);
});

observe(() => {
  const id = setInterval(refresh, props.interval);
  return () => clearInterval(id);
});
```

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `fn` | `() => unknown` | Runs immediately, then after any value it read changes. If it returns a function, that function runs before the next run and when the observer stops |

Returns a `stop()` function.

## Behaviour

| Topic | Behaviour |
| --- | --- |
| Dependencies | Collected fresh on every run: only what the last run read is watched |
| Batching | Re-runs are queued and run once per microtask, after all synchronous writes |
| Lifetime | In a component script, stops automatically when the element is removed. The exported `observe` from `@realmorg/realm` is not tied to any element |
| `refs` | An observer at the top of a script sees `refs` once the markup exists, because `refs` is reactive |
| Errors | A throwing observer is reported with `console.error`. Other observers keep running |
| Loops | If observers keep re-triggering each other for 100 rounds in one flush, the queue is cleared and `Update loop detected` is reported |
| Reading without subscribing | Wrap reads in [`untrack`](/reference/javascript/untrack/), imported from `@realmorg/realm` (it is not one of the script helpers) |

## Example

```html live
<custom-element name="title-mirror">
  <script type="realm">
    const draft = useState({ text: "REALM" });
    const log = useState({ runs: 0 });
    let runs = 0;

    observe(() => {
      refs.preview?.style.setProperty("letter-spacing", `${draft.text.length / 20}em`);
      log.runs = ++runs;
    });
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      width: min(calc(var(--spacing) * 100), 100%);
    }
  </style>

  <input aria-label="Text" _value="#draft.text" oninput="draft.text = this.value">
  <strong ref="preview"><slot name="#draft.text"></slot></strong>
  <small>Observer runs: <slot name="#log.runs"></slot></small>
</custom-element>

<title-mirror></title-mirror>
```

## Related

- [State and reactivity: observe](/docs/state/#observe)

## Calling other components from an observer

An observer subscribes to everything it reads, including state read inside another component's methods. Wrap such calls in `untrack` so the observer runs only when its own inputs change:

```js
observe(() => {
  if (order.status === "error") untrack(() => refs.dialog.showModal());
});
```


---

# `tick`

Source: http://realm.js.org/reference/script/tick/

Waits until pending updates have been applied to the DOM.

```ts
tick(): Promise<void>
```

```js
async function add() {
  todo.items.push(item);
  await tick();
  refs.list.lastElementChild.scrollIntoView();
}
```

## Behaviour

State changes are applied once per microtask. `tick()` waits one microtask and then [flushes](/reference/javascript/flush/) whatever is still queued, so after `await tick()` bindings, slots, lists and conditions show the new state.

| Returns | Meaning |
| --- | --- |
| `Promise<void>` | Resolves after the flush |

## Example

```html live
<custom-element name="tick-list">
  <script type="realm">
    const log = useState({ lines: ["Line 1"] });

    async function add() {
      log.lines.push(`Line ${log.lines.length + 1}`);
      await tick();
      refs.list.scrollTop = refs.list.scrollHeight;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      justify-items: start;
    }
    div {
      width: calc(var(--spacing) * 60);
      height: calc(var(--spacing) * 24);
      overflow: auto;
      border: 1px solid var(--border);
      border-radius: var(--radius-md);
      padding: calc(var(--spacing) * 2);
    }
    p {
      margin: 0;
    }
  </style>

  <ui-button onclick="add()">Add a line</ui-button>
  <div ref="list"><p repeat="#log.lines" as="line"><slot name="#line"></slot></p></div>
</custom-element>

<tick-list></tick-list>
```

The new line is in the DOM after `await tick()`, so scrolling reaches it.

## Related

- [State and reactivity: tick](/docs/state/#tick)


---

# `defineStore`

Source: http://realm.js.org/reference/script/define-store/

Returns the app-wide reactive store called `name`, creating it on the first call. Available in every script and exported from `@realmorg/realm`.

```ts
defineStore<T extends object>(name: string, initial: T, options?: StoreOptions): T

interface StoreOptions {
  persist?: "local" | "session" | StorageAdapter;
}

interface StorageAdapter {
  get(key: string): string | null;
  set(key: string, value: string): void;
}
```

```js
const cart = defineStore("cart", {
  items: [],
  get count() {
    return this.items.length;
  },
}, { persist: "local" });
```

## Parameters

| Parameter | Type | Default | Meaning |
| --- | --- | --- | --- |
| `name` | `string` | required | Store name, shared by the whole page |
| `initial` | plain object | required | Initial state. Used only on the first call for this name |
| `options.persist` | `"local"`, `"session"` or `StorageAdapter` | none | Save the store after every change and restore it on creation |

Returns the same reactive proxy for every call with the same `name`. Later calls ignore `initial` and `options`.

## Persistence

| Topic | Behaviour |
| --- | --- |
| Key | `realm:<name>` |
| Format | `JSON.stringify(store)`, written once on creation and again after every change (batched per microtask) |
| Restore | On creation, each saved field that is a data property of `initial` is written to the store. Getter values are ignored |
| Corrupt data | Logs `Stored value for store "name" is not valid JSON and was ignored.` and keeps `initial` |
| `"local"` / `"session"` | `localStorage` / `sessionStorage` |
| Custom adapter | Any object with synchronous `get(key)` and `set(key, value)`, for example one backed by cookies or an in-memory `Map` |

## Sharing a store

Two components that call `defineStore("cart", …)` get the same object. To share one definition, put it in a module and import it:

```js
// cart.js
import { defineStore } from "https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/index.js";

export const cart = defineStore("cart", { items: [] }, { persist: "local" });
```

Use the same version for `index.js` (or `realm.js`) as the page uses to start REALM. Both files load the same runtime chunk, so the store is shared.

## Example

```html live
<custom-element name="store-add">
  <script type="realm">
    const basket = defineStore("reference-basket", { items: [] });

    function add() {
      basket.items.push(`Item ${basket.items.length + 1}`);
    }
  </script>

  <ui-button onclick="add()">Add an item</ui-button>
</custom-element>

<custom-element name="store-count">
  <script type="realm">
    const basket = defineStore("reference-basket", { items: [] });
  </script>

  <p>The basket holds <slot name="#basket.items.length"></slot> items.</p>
</custom-element>

<store-add></store-add>
<store-count></store-count>
```

## Related

- [Stores](/docs/stores/)


---

# `host`

Source: http://realm.js.org/reference/script/host/

The component element itself.

```ts
host: HTMLElement
```

```js
host.toggleAttribute("open", true);
host.closest("form");
host.shadowRoot.querySelector("input");
```

## Notes

| Topic | Detail |
| --- | --- |
| Shadow root | `host.shadowRoot` is the open shadow root that holds the markup. It is empty while the script's top level runs |
| Attributes | For reactive attribute reads, use [`attrs`](/reference/script/attrs/) or [`defineProps`](/reference/script/define-props/) |
| Events | Prefer [`dispatch`](/reference/script/dispatch/) to send events and [`listen`](/reference/script/listen/) to receive them, so listeners are removed with the element |
| In markup | `host` is not exposed to references. Inside handlers, `host` is in scope |

## Example

```html live
<custom-element name="host-size">
  <script type="realm">
    const size = useState({ width: 0 });

    onConnected(() => {
      const observer = new ResizeObserver(() => {
        size.width = Math.round(host.getBoundingClientRect().width);
      });
      observer.observe(host);
      return () => observer.disconnect();
    });
  </script>

  <style type="realm">
    /* The text never wraps, so writing the width cannot change the size again. */
    :host {
      display: block;
      resize: horizontal;
      overflow: hidden;
      white-space: nowrap;
      width: calc(var(--spacing) * 60);
      padding: calc(var(--spacing) * 3);
      border: 1px solid var(--border);
      border-radius: var(--radius-md);
    }
  </style>

  Drag the corner. Width: <slot name="#size.width"></slot>px
</custom-element>

<host-size></host-size>
```

## Related

- [Lifecycle: host, refs and internals](/docs/lifecycle/#host-refs-and-internals)


---

# Security

Source: http://realm.js.org/docs/security/

REALM treats some sources as code and everything else as data.

| Source | Treated as |
| --- | --- |
| Component definitions, inline or loaded with `<import-element>` | **Code**, like a `<script src>` |
| Native `on*` handler attributes in definition markup | **Code**, compiled with the component's script |
| Every other attribute in markup | **References only.** No expression is ever evaluated |
| Value slots | **Text**, unless the slot has `html` |
| HTML inserted later: `html` slots, `render` responses | **Data.** Sanitised, and never scanned for handlers, references or bindings |
| Responses loaded with `into` | **Data.** Shown as text by slots and bindings |

## Sanitising

`<slot name="#x" html>` and the `render` fetch attribute parse the HTML with `DOMParser` and remove:

- the elements `script`, `style`, `iframe`, `frame`, `frameset`, `object`, `embed`, `link`, `meta`, `base`, `template` and `noscript`,
- every attribute that starts with `on`, and `srcdoc`,
- `href`, `src`, `action`, `formaction`, `xlink:href` and `poster` values that start with `javascript:`, `vbscript:` or `data:text/html`.

The sanitiser is deliberately small. It blocks script execution, but it does not limit layout or styling attributes, and it does not stop a `<form>` in untrusted HTML from posting somewhere. For user-generated rich text, sanitise on the server with an allow-list as well.

`html-unsafe` skips sanitising. Only use it for HTML you produced yourself.

Text values are always inserted as text nodes, and attribute bindings use `setAttribute`, so state values cannot inject markup. A bound URL attribute such as `_href="#link.url"` is set as given. Validate URLs that come from users before putting them in state.

## No eval

REALM never uses `eval`, `new Function` or `blob:` URLs. Component scripts and their handlers are assembled into a script element and inserted into the page. Handler attributes on plain pages for custom events are compiled the same way.

## Content Security Policy

REALM works under a nonce-based policy. Give the page's REALM `<script>` tag a nonce. REALM copies the nonce from the first `script[nonce]` in the document onto every script it inserts:

```html
<meta http-equiv="Content-Security-Policy" content="script-src 'nonce-r4nd0m' 'strict-dynamic'; style-src 'self' 'unsafe-inline'">
<script type="module" nonce="r4nd0m" src="/realm/realm.js"></script>
```

- Send the policy as an HTTP header in production, and generate a new nonce for every response.
- `'strict-dynamic'` lets scripts loaded by trusted scripts run, which covers module imports from component scripts.
- Event handlers in component markup are not inline handler attributes as far as the browser is concerned (REALM removes the attribute and compiles the handler into the component's script), so you do not need `'unsafe-inline'` or `'unsafe-hashes'` for them.
- Component styles are constructable stylesheets. REALM itself also sets inline `style` custom properties for `--attr-*`, `--state-*` and `_--name` bindings. Allow inline styles if you use those.

Limits:

- **Hash-only policies** (`script-src 'sha256-…'` without a nonce) cannot allow scripts that are assembled at runtime. Use a nonce.
- **Trusted Types** (`require-trusted-types-for 'script'`) is not supported yet, because REALM assigns the assembled script's text directly.

## Imported components

`<import-element from="https://…">` runs code from that origin in your page, like a `<script src>`. Only import from origins you trust, pin versions on CDNs, and restrict them with `script-src` and `connect-src`.

## Checklist

- Keep untrusted HTML out of `html-unsafe`.
- Sanitise rich text on the server too.
- Validate user-provided URLs before binding them to `href` or `src`.
- Use a nonce-based CSP with `'strict-dynamic'`.
- Import components only from trusted, pinned sources.


---

# Performance and memory

Source: http://realm.js.org/docs/performance/

REALM has no virtual DOM and never re-runs a component. Each slot, binding, condition and loop subscribes to the values it reads, and only those update.

## Updates

- **Fine-grained.** Changing `todo.items[3].done` updates the bindings that read that field, not the component.
- **Batched.** Writes are collected and applied once per microtask, so ten writes in a row cost one update per affected binding.
- **Cached derived values.** Getters on state recompute only after an input changed, and only once even when several inputs changed.
- **Same value, no work.** Writing the value a property already has notifies nobody.
- **Loop protection.** An observer that keeps changing its own input is stopped after 100 rounds with an error, instead of freezing the tab.

## Lists

Keyed lists (`key="id"`) reuse rows for items that stay, move rows instead of re-creating them, and only build rows for new items. Without a key, rows are matched by position. Set a key on long lists that are often reordered.

## Components

- **One definition per type.** A component's markup, handlers and styles are prepared once. Each instance clones the prepared markup and connects bindings.
- **Shared stylesheets.** Styles are constructable stylesheets adopted by every instance. Nothing is parsed per instance.
- **No work in the constructor.** Setup runs when the element connects, following the custom element rules.

## Loading

- The runtime is about 15 KB gzipped, plus 1 KB of CSS.
- `<import-element>` fetches each URL once, however many tags or components ask for it, and runs at most six requests per origin at a time.
- `loading="lazy"` with `for` defers a file until one of its tags is used.
- Identical `GET` requests from fetch attributes made at the same time are sent once.
- `realm.css` hides undefined custom elements, so nothing flashes unstyled while files load.

## Memory and cleanup

Everything a component starts is tied to its `AbortSignal`, which aborts when the element is removed (one microtask after removal, so moving an element does not trigger cleanup):

| Started by | Stopped on removal |
| --- | --- |
| `observe` in a component | The observer and its cleanup function |
| Event handlers in markup, `listen()` | The listeners, including ones on `document` and `window` |
| `debounce` timers | Pending calls are cancelled |
| Fetch attributes | In-flight requests are aborted. `poll` intervals and `visible` observers stop |
| `useChildren`, prop and attribute watchers | Their mutation observers disconnect |
| `onConnected` | The returned cleanup function runs |
| `defineMethods`, `defineProps` | The added properties and methods are removed from the element |
| Content removed by `<is-visible>`/`<is-hidden>` or a list update | All of the above for that content |

Then the shadow root is emptied, so detached elements hold no subtree.

REALM cannot clean up what you start yourself without the signal. Use the helpers instead:

```js
// Leaks: nothing removes these
window.addEventListener("resize", measure);
setInterval(refresh, 5000);

// Cleaned up on removal
listen("resize", measure, window);
observe(() => {
  const id = setInterval(refresh, 5000);
  return () => clearInterval(id);
});
fetch(url, { signal });
```

Stores are never cleaned up. They live as long as the page.

## Measuring

The runtime has memory and performance test suites in Chromium. The memory suite mounts and removes a component with observers, timers, window listeners, debounced handlers, conditions, lists and a polling fetch 1,000 times. It then forces garbage collection and checks that every instance was collected. It does the same for rows removed from keyed lists. The performance suite holds keyed list operations to time budgets.

In your app, use the browser's Performance panel and heap snapshots. Detached REALM elements should not appear in retained trees after removal.


---

# `refs`

Source: http://realm.js.org/reference/script/refs/

Elements with a [`ref="name"`](/reference/attributes/ref/) attribute in the component's markup, keyed by name.

```ts
refs: Record<string, Element>
```

```html
<canvas ref="chart"></canvas>
```

```js
onConnected(() => {
  const context = refs.chart.getContext("2d");
});
```

## Behaviour

| Topic | Detail |
| --- | --- |
| Timing | Empty while the script's top level runs. Filled as the markup is processed, before `onConnected` hooks |
| Reactive | `refs` is a reactive object, so an [`observe`](/reference/script/observe/) that reads `refs.chart` runs again once the element exists |
| Loops and conditions | Elements inside `repeat` or `<is-visible>` are added when they are mounted. The last mounted element with a name wins, and removed content is not taken out |
| `ref="control"` | Also makes the element the delegated form control in `form-associated` components. See [`ref`](/reference/attributes/ref/#ref-control) |

## Example

```html live
<custom-element name="draw-dot">
  <script type="realm">
    function draw(event) {
      const canvas = refs.canvas;
      const box = canvas.getBoundingClientRect();
      const context = canvas.getContext("2d");
      context.fillStyle = getComputedStyle(host).color;
      context.beginPath();
      context.arc(event.clientX - box.left, event.clientY - box.top, 4, 0, Math.PI * 2);
      context.fill();
    }
  </script>

  <style type="realm">
    canvas {
      border: 1px solid var(--border);
      border-radius: var(--radius-md);
      cursor: crosshair;
    }
  </style>

  <canvas ref="canvas" width="240" height="120" onclick="draw(event)"></canvas>
</custom-element>

<draw-dot></draw-dot>
```

## Related

- [`ref` attribute](/reference/attributes/ref/)


---

# Browser support

Source: http://realm.js.org/docs/browser-support/

REALM targets current evergreen browsers: the latest versions of Chrome, Edge, Firefox and Safari. There is no build step that could down-level the runtime, and there is no legacy fallback.

Every runtime test runs in Chromium, Firefox and WebKit through Playwright, and the site's example apps are tested end to end in all three.

## Minimum versions

The oldest versions that have every platform feature REALM uses:

| Browser | Version |
| --- | --- |
| Chrome and Edge | 125 |
| Firefox | 126 |
| Safari (macOS and iOS) | 17.4 |

The limiting feature is `CustomStateSet` with the `:state()` selector, which REALM uses for reactive CSS and loading states.

## Platform features used

| Feature | Used for |
| --- | --- |
| Custom elements and shadow DOM | Every component |
| Constructable stylesheets (`adoptedStyleSheets`) | Component styles, shared per type |
| `ElementInternals`, `CustomStateSet` and `:state()` | Roles, form association, reactive CSS states, `:state(loading)` |
| Form-associated custom elements | `form-associated` components |
| `delegatesFocus` | `delegates-focus` components |
| `Proxy`, `WeakMap`, microtasks | Reactivity |
| `AbortController` and `AbortSignal` | Cleanup and request cancellation |
| `DOMParser` | Loading component files and sanitising HTML |
| `IntersectionObserver` | `trigger="visible"` |
| ES2023 (`findLast`, `toReversed`) and `URL.canParse` | Runtime code and URL props |

## Polyfilled or emulated

- **focusgroup.** The `focusgroup` attribute is a proposal that only the newest Chromium versions have started to ship. REALM implements its arrow-key behaviour itself, so it works in every supported browser. See [Accessibility](/docs/accessibility/).
- **Invoker commands.** `ui-button` supports `commandfor` and `command` natively where the browser has them, and emulates `show-modal`, `close` and the popover commands elsewhere.

REALM UI also uses the Popover API and `<dialog>`, both available in the versions above.

## Not supported

- Internet Explorer and the legacy (EdgeHTML) Edge.
- Browsers with JavaScript disabled: components render nothing without the runtime. See [Modern framework problems](/docs/framework-problems/) for server rendering.


---

# `signal`

Source: http://realm.js.org/reference/script/signal/

An `AbortSignal` that aborts when the element is removed (not when it is moved).

```ts
signal: AbortSignal
```

```js
fetch(`/api/users/${props.id}`, { signal })
  .then((response) => response.json())
  .then((user) => (profile.user = user));

window.addEventListener("resize", layout, { signal });
```

## Behaviour

| Topic | Detail |
| --- | --- |
| When it aborts | After [`onDisconnected`](/reference/script/on-disconnected/) hooks run, when the element is removed |
| What else uses it | [`listen`](/reference/script/listen/), handler attributes, fetch attributes and the [element-bound timers](/reference/script/timers/) |
| Use it for | `fetch`, `addEventListener` on other targets, `AbortSignal.any`, and any API that accepts a signal |

## Example

```html live
<custom-element name="pointer-tracker">
  <script type="realm">
    const pointer = useState({ x: 0, y: 0 });

    document.addEventListener("pointermove", (event) => {
      pointer.x = event.clientX;
      pointer.y = event.clientY;
    }, { signal });
  </script>

  <p>Pointer: <slot name="#pointer.x"></slot>, <slot name="#pointer.y"></slot></p>
</custom-element>

<pointer-tracker></pointer-tracker>
```

The document listener is removed when `<pointer-tracker>` is removed.

## Related

- [Lifecycle: signal](/docs/lifecycle/#signal)


---

# `internals`

Source: http://realm.js.org/reference/script/internals/

The element's `ElementInternals`, attached by REALM.

```ts
internals: ElementInternals
```

```js
internals.states.add("expanded");
internals.ariaExpanded = "true";
internals.setFormValue(props.value);
```

## What it is used for

| Member | Use |
| --- | --- |
| `states` | Custom states for CSS: `internals.states.add("open")` matches `:host(:state(open))` and `tag:state(open)` |
| `role`, `aria*` | Default ARIA role and properties. The definition's `role` attribute sets `internals.role` |
| `setFormValue(value)` | The value submitted with the form (form-associated components) |
| `setValidity(flags, message, anchor)` | Validation state |
| `form`, `labels`, `validity`, `validationMessage`, `willValidate`, `checkValidity()`, `reportValidity()` | Form association |

REALM uses `internals.states` for the [reactive `:state()` selectors](/reference/css/states/) and `:state(loading)`. In form-associated components with a `value` prop, REALM calls `setFormValue` for you, and with [`ref="control"`](/reference/attributes/ref/#ref-control) it calls `setValidity`.

## Example

```html live
<custom-element name="expand-box">
  <script type="realm">
    function toggle() {
      if (internals.states.has("expanded")) internals.states.delete("expanded");
      else internals.states.add("expanded");
    }
  </script>

  <style type="realm">
    :host {
      display: block;
      max-width: calc(var(--spacing) * 100);
    }
    p {
      display: none;
    }
    :host(:state(expanded)) p {
      display: block;
    }
  </style>

  <ui-button variant="outline" onclick="toggle()">Toggle details</ui-button>
  <p>Details shown through a custom state.</p>
</custom-element>

<expand-box></expand-box>
```

## Related

- [Styling: your own states](/docs/styling/#your-own-states)
- [Forms: doing it by hand](/docs/forms/#doing-it-by-hand)


---

# Modern framework problems and how REALM handles them

Source: http://realm.js.org/docs/framework-problems/

This page lists common front-end framework problems and how REALM handles each one, including where it has no answer yet. "Gap" marks a known limitation.

| Problem | How REALM handles it | Status |
| --- | --- | --- |
| **Flash of unstyled content (FOUC)** | `realm.css` hides custom elements until they are defined (`:not(:defined)`) and hides definitions and `<import-element>`. Styles are adopted before a component's markup is inserted, so a component never appears unstyled | Handled. The trade-off: content is invisible until its definition loads |
| **Hydration mismatches and glitches** | There is no server render to hydrate. Components render once, in the browser, from their definition | Not applicable |
| **SSR and SEO** | Light DOM content you write inside components (headings, paragraphs, links placed in slots) is in the HTML and indexable. Shadow DOM content is created by JavaScript. Search engines that run JavaScript see it. Others do not | **Gap.** No server-side rendering yet. Declarative Shadow DOM output is planned after 2.0. Keep important text in light DOM |
| **Bundle size** | About 15 KB gzipped for the whole runtime, no compiler, no per-component runtime cost beyond your own code | Handled |
| **Build tooling** | None required. Components are HTML files. Scripts are plain JavaScript | Handled. A bundler is optional |
| **Memory leaks** | Every listener, observer, timer, debounce, poll and request is tied to the element's `AbortSignal`. Removal aborts it and empties the shadow root. A memory test mounts and removes components 1,000 times and checks they are collected | Handled for everything started through REALM. Code you start without `signal` is yours to stop |
| **Stale closures** | Components never re-run, so there is no "closure from an old render". Functions read state through live proxies at call time, and loop handlers receive the current item | Handled |
| **Effect dependency arrays** | `observe` tracks what it reads, so there is no array to get wrong | Handled |
| **Over-rendering** | Fine-grained subscriptions: a change updates only the slots and bindings that read it. Updates are batched per microtask | Handled |
| **Infinite update loops** | An observer that keeps changing its own input is stopped after 100 rounds with an error | Handled |
| **Race conditions in data fetching** | A new request from an element aborts its previous one. Identical `GET`s in flight are shared. Requests abort when the element is removed. Errors never render | Handled for fetch attributes. For `fetch()` in scripts, pass `signal` and handle ordering yourself |
| **Loading and error states** | `busy="#ref"`, `aria-busy`, `:state(loading)`, and native `loadstart`/`load`/`error`/`abort`/`timeout`/`loadend` events | Handled |
| **XSS** | Markup holds references, never expressions. Values are inserted as text. `html` slots and `render` sanitise (scripts, `on*` attributes, `javascript:` URLs removed) and inserted HTML is never scanned for handlers | Handled for the common cases. The sanitiser is a deny-list: sanitise user rich text on the server too, and never use `html-unsafe` for untrusted input |
| **Content Security Policy** | No `eval`, `new Function` or `blob:`. REALM copies the page's script nonce onto the scripts it assembles. Markup handlers are compiled into the component script, not inline attributes | Handled for nonce-based policies. **Gap:** hash-only policies and Trusted Types are not supported |
| **Style leaks and CSS conflicts** | Component styles live in shadow roots and cannot leak out. Page styles cannot leak in except through inherited properties | Handled |
| **Theming across components** | Design tokens as CSS custom properties, `part` for inner elements, custom states for variants, `data-theme` for dark mode | Handled |
| **Custom form inputs** | `form-associated` components submit, reset, validate, disable and restore through `ElementInternals`. `ref="control"` delegates to a native control | Handled |
| **Accessibility** | Native elements inside components, default roles through `ElementInternals`, `delegates-focus`, a `focusgroup` implementation for arrow-key navigation, ARIA bindings that write `"true"`/`"false"`, `aria-busy` on requests | Partly. Roles set through `ElementInternals` are invisible to some audit tools, and you are still responsible for your own components' semantics |
| **Prop drilling and global state** | Nested components read parent state automatically (with a one-time warning), and `defineStore` provides app-wide, optionally persisted state | Handled |
| **"Already defined" registration errors** | Defining the same component twice does nothing. Conflicting definitions keep the first and warn. Imports of the same file are shared | Handled |
| **Request waterfalls when loading components** | Each file is fetched once, at most six at a time per origin. Bundles hold many components. `loading="lazy"` defers files | Partly. Components imported by other component files are discovered only when those load. Bundle components that are always used together |
| **Error isolation** | A syntax error in one component's script, or an error thrown during setup, is reported and that component still renders its markup. Errors in observers do not stop other observers | Partly. There is no error-boundary API to render fallback UI |
| **TypeScript and editor support** | The package ships type declarations for its exports | **Gap.** Component scripts are not type-checked, and there is no editor plugin for references and props yet |
| **Routing** | Links with `render` load another page's content into a ref and update the address bar | **Gap.** No client-side router. Use normal page navigation or `render` links |
| **Very long lists** | Keyed lists reuse and move rows | **Gap.** No built-in virtualisation |
| **Interop with other frameworks** | REALM components are standard custom elements: they take attributes and properties and emit DOM events, so they work in any framework or none | Handled |
| **Debugging** | One-time `[realm]` console warnings that name the component, the attribute and the rule. Assembled scripts get a `sourceURL` named after the component file | Partly. No devtools extension |

## When REALM is a good fit

- Sites and apps where pages are HTML and interactivity is per component: dashboards, admin tools, documentation, marketing sites with interactive parts, internal apps.
- Teams that want to avoid a toolchain, or want components that work in any stack.

## When to look elsewhere

- Pages that must render fully without JavaScript or need server rendering for SEO today.
- Very large single-page apps that need a router, code-splitting strategy and type-checked templates built in.


---

# `attrs`

Source: http://realm.js.org/reference/script/attrs/

Reactive access to every attribute on the host, declared as a prop or not.

```ts
attrs: Record<string, string | null>
```

```js
const view = useState({
  get compact() {
    return attrs.density === "compact";
  },
});

attrs.tabindex ??= 0;
attrs["aria-expanded"] = open;
```

## Reading

| Read | Result |
| --- | --- |
| `attrs.name` | The attribute's text, or `null` when it is absent |
| In an observer or getter | Subscribes. It re-runs when that attribute changes, is added or is removed |

## Writing

| Value written | Result |
| --- | --- |
| `null`, `undefined`, `false` | `removeAttribute(name)` |
| `true` | `setAttribute(name, "")` |
| anything else | `setAttribute(name, String(value))` |

The attribute mirror is created on first use and watches the host with a `MutationObserver` until the element is removed. For typed, validated attributes, use [`defineProps`](/reference/script/define-props/).

## Example

```html live
<custom-element name="density-label">
  <script type="realm">
    const view = useState({
      get text() {
        return attrs.density === "compact" ? "Compact" : "Comfortable";
      },
    });

    function toggle() {
      attrs.density = attrs.density === "compact" ? null : "compact";
    }
  </script>

  <ui-button variant="outline" onclick="toggle()"><slot name="#view.text"></slot></ui-button>
</custom-element>

<density-label></density-label>
```

## Related

- [Props: attributes and properties](/docs/props/#attributes-and-properties)


---

# Migrating from v1

Source: http://realm.js.org/docs/migrating-from-v1/

REALM v2 keeps v1's vocabulary where it worked (`<custom-element>`, `<slot name="#…">`, `@` and `#` references, `_` bindings, `<is-visible>`, `<repeat-list>`, `<import-element>`) and replaces the tag language for logic with a plain JavaScript `<script>`. Most migrations are mechanical.

Read [What's new in REALM v2](/blog/realm-v2/) for the reasons behind the changes.

## The same component in both versions

v1:

```html
<custom-element name="counter-button">
  <element-state name="count" type="number">0</element-state>
  <element-flow>
    <trigger-event click="button">
      <set-state name="count" mutate="+" value="1"></set-state>
    </trigger-event>
  </element-flow>
  <template>
    <style>
      button { font-weight: bold; }
    </style>
    <button ref="button">Clicked <slot name="#count"></slot> times</button>
  </template>
</custom-element>
```

v2:

```html
<custom-element name="counter-button">
  <script>
    const counter = useState({ count: 0 });

    function increment() {
      counter.count++;
    }
  </script>

  <style>
    button { font-weight: bold; }
  </style>

  <button onclick="increment()">Clicked <slot name="#counter.count"></slot> times</button>
</custom-element>
```

## Step by step

1. **Update the scripts.** Replace v1's `realm.production.min.js` and `realm.min.css` with v2's `realm.js` (a module script) and `realm.css`. See [Installation](/docs/installation/).
2. **Remove `<template>`.** Move its markup and `<style>` directly into `<custom-element>`.
3. **Turn `<element-attr>` into `defineProps`.** Each attribute becomes a prop with a type and default.
4. **Turn `<element-state>` into `useState`.** Group related states into one object. Update references from `#count` to `#counter.count`.
5. **Replace `<element-flow>`.** Each `<trigger-event>` becomes a native `on*` attribute on the element that had the `ref`, calling a function. Each `<set-state>` becomes an assignment in that function.
6. **Replace `<http-request>`** with fetch attributes (`fetch`, `into`, `render`, `busy`) and `onload`/`onerror`.
7. **Replace `<global-state>`** with parent state or `defineStore`.
8. **Mark inline definitions.** If you defined components directly in the page, give the script and style `type="realm"`.
9. **Check the console.** v2 warns about invalid references, props and duplicate definitions, naming the component.

## Cheat sheet

| v1 | v2 |
| --- | --- |
| `<template>` around markup and styles | No wrapper. `<script>`, `<style>` and markup sit directly in `<custom-element>` |
| `<element-attr name="count" type="number">0</element-attr>` | `defineProps({ count: prop.number().default(0) })` |
| `<element-state name="items" type="array">[]</element-state>` | `const todo = useState({ items: [] })` |
| `<set-state name="count" mutate="+" value="1">` | `counter.count++` in a function |
| `<set-state name="items" mutate="push" …>` | `todo.items.push(item)` |
| `<set-attr name="x" …>` | `attrs.x = value`, or a reflected prop |
| `<set-timer every="1000">` | `observe(() => { const id = setInterval(…); return () => clearInterval(id); })` |
| `<slot name="#count"></slot>` | `<slot name="#counter.count"></slot>`. Now a native slot that adds no element to the page |
| `<slot name="@label"></slot>` | Unchanged |
| `_href="#url"` | `_href="#link.url"`. References now include the state object |
| `<is-visible value="#x" eq="1">` | `<is-visible when="#state.x" eq="1">`. Hidden content is now removed, not hidden with CSS |
| `<repeat-list of="#items">` with `$.label` and `!.index` | `<repeat-list of="#todo.items" as="item" index="i" key="id">` with `#item.label` and `#i`. Inside lists and tables, use the `repeat` attribute |
| `<element-flow>` with `<trigger-event click="ref">` | `onclick="save()"` on the element |
| `debounce` on `<trigger-event>` | `debounce` on the element |
| `<listen-event mounted>` | `onConnected(() => …)` |
| `<listen-event on="name">` | `onname="handle(event)"` |
| `<listen-event statechanged="x">` | `observe(() => …)` or a getter |
| `<send-event name="x">` | `dispatch("x", detail)` or `host.dispatchEvent(new CustomEvent("x", …))` |
| `<script type="module/realm" use="localState, event">` | The component's `<script>` |
| `<http-request>` with `<response-ok>` and `<response-fail>` | `fetch`, `into`, `render` and `busy` attributes, with `onload` and `onerror` |
| `<global-state name="x" storage="localStorage">` | `defineStore("x", { … }, { persist: "local" })`. Values now keep their types |
| `<slot global name="#counter">` | `<slot name="#app.counter">` where `app` is a store imported into the component |
| `<import-script>`, `<import-style>` | `import` in the component script, `<link rel="stylesheet">` in the definition |
| `<web-app>` | Not needed |
| CSS `var(--attr-x)` | Unchanged |
| CSS `var(--state-x)` | `var(--state-theme-color)`, the reference path `#theme.color` with dashes |
| CSS `var(--global-x)` | Read the store in a getter and use `var(--state-…)` |
| CSS `:host([\@number][gt="5"])` | `:host(:state(attr-number-gt-5))` |
| CSS `:host([\#counter][eq="5"])` | `:host(:state(state-counter-count-is-5))` |

## Behaviour changes to watch for

- **Hidden content stops.** v1's `<is-visible>` hid content with CSS, so it kept running. v2 removes it, with its listeners and requests. Use `_hidden` when content must stay in the DOM.
- **Lists keep their rows.** v1 rebuilt lists on every change, which lost focus and typed text and stacked duplicate listeners. With `key`, v2 reuses and moves rows.
- **Stored values keep their types.** v1 returned numbers from storage as strings. Code that converted them back can drop the conversion.
- **Imports are shared.** v1 fetched a file once per `<import-element>` and could throw "already defined". v2 fetches each URL once and defines every component in the file, not only the first.
- **Requests cancel stale ones.** A slower, older response can no longer overwrite a newer one.
- **No globals.** v1 wrote `window.globalState`. v2 attaches nothing to `window`.
- **Inline scripts are not run through `blob:` URLs**, so v2 works under a nonce-based Content Security Policy.
- **Elements are set up on connect**, not in the constructor, so components created with `document.createElement` work.

## Getting help

If something from v1 has no equivalent here, open an issue on [GitHub](https://github.com/realmorg/realm/issues) with the v1 markup.


---

# Use REALM with coding assistants

Source: http://realm.js.org/docs/ai-skill/

Coding assistants know the big frameworks well and REALM hardly at all. Left alone, they write `{{ }}` in markup, expressions in attributes and React-style state. The REALM agent skill fixes that: a folder of Markdown that teaches an assistant how REALM, REALM UI and Unicons really work, which it reads only when a task needs it.

## What the skill contains

The skill follows the [Agent Skills](https://agentskills.io) format: a `SKILL.md` with the core rules, plus reference files the assistant opens on demand.

| File | Covers |
| --- | --- |
| `SKILL.md` | When to use the skill, the mental model, CDN setup, a quick start and the hard rules (no interpolation, references only in attributes, `type="realm"` for inline definitions, `repeat` inside lists, compound parts, design tokens) |
| `references/api.md` | Every script helper with its signature and an example |
| `references/markup.md` | Definitions, references, value slots, bindings, handlers, control flow, lists, `ref`, `focusgroup` |
| `references/fetching.md` | Every fetch attribute, trigger, mode and event |
| `references/imports.md` | `<import-element>`, component files, dependencies and shared modules |
| `references/styling.md` | `:host`, reactive CSS, custom states and the theme tokens |
| `references/forms-a11y.md` | Form-associated components and accessibility |
| `references/ui-components.md` | Every REALM UI component: tags, parts, attributes, events and a usage snippet |
| `references/unicons.md` | `<u-icon>` and its icon sets |
| `references/recipes.md` | A todo list, a fetched list, a validated form, dialogs, a dashboard and a multi-page app |
| `references/pitfalls.md` | Common mistakes and every console message REALM prints |
| `references/testing.md` | How to check a page in a browser |

The skill is generated and tested in the REALM repository. Every runnable example in it runs in Chromium in CI, and every helper, attribute and tag it names is checked against the runtime.

## Claude Code

Install it with the [`skills` CLI](https://github.com/vercel-labs/skills), from your project:

```bash
npx skills add realmorg/realm
```

The CLI asks which assistants to install it for. To skip the questions, or to install it for every project:

```bash
npx skills add realmorg/realm --skill realm -a claude-code
npx skills add realmorg/realm --skill realm -a claude-code -g
```

Or copy it by hand. Claude Code reads skills from `.claude/skills/` in a project and `~/.claude/skills/` for all projects:

```bash
curl -LO https://realm.js.org/skills/realm.zip
unzip realm.zip -d ~/.claude/skills/
```

The skill is then at `~/.claude/skills/realm/SKILL.md`. Claude Code loads it when a task involves REALM, or when you ask it to use the `realm` skill.

## Codex, Cursor and other assistants

The same command installs the skill for any assistant the CLI supports. Pass its name with `-a`:

```bash
npx skills add realmorg/realm --skill realm -a codex
npx skills add realmorg/realm --skill realm -a cursor
```

| Assistant | Project folder | Global folder |
| --- | --- | --- |
| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
| Codex | `.agents/skills/` | `~/.agents/skills/` |
| Cursor | `.agents/skills/` | `~/.cursor/skills/` |

To install by hand, unzip [realm.zip](/skills/realm.zip) into one of these folders. The [skills CLI agent list](https://github.com/vercel-labs/skills/blob/main/docs/agents.md) has the folders for other assistants.

An assistant without skill support can still use it: add a line to its rules file (`AGENTS.md`, `.cursor/rules/`, `CLAUDE.md`) that says "When writing REALM code, read `skills/realm/SKILL.md` first", with the folder copied into the project.

## Download

- [realm.zip](/skills/realm.zip): the whole skill, in a `realm/` folder.
- The raw files, for reading or linking: [SKILL.md](/skills/realm/SKILL.md) and the [references](/skills/realm/references/ui-components.md) next to it.

## llms.txt and Markdown pages

For assistants that read the web instead of a skill:

- [llms.txt](/llms.txt) lists every page of this site with a one-line summary.
- [llms-full.txt](/llms-full.txt) is the whole site as one Markdown file.
- Every page has a Markdown copy at the same address with `.md` instead of the trailing slash, such as [docs/state.md](/docs/state.md). The "View as Markdown" link at the bottom of each page opens it.

## Tips

- Ask for REALM by name ("build this as a REALM component"), so the assistant reaches for the skill.
- Ask it to check the result in a browser and read the console. Every `[realm]` warning names the component and the problem, and the skill lists the fix for each one.
- Keep the CDN setup. REALM needs no `npm install` and no bundler, and the skill tells assistants not to add them.


---

# `useChildren`

Source: http://realm.js.org/reference/script/use-children/

A reactive array of the host's direct light DOM children that match a selector. Used by components that take `<option>`-like children.

```ts
useChildren(selector: string, attributes?: string[]): Element[]
```

```js
const options = useChildren("option", ["value", "label", "disabled"]);
const menu = useState({
  get items() {
    return options.map((option) => ({ value: option.value, label: option.label }));
  },
});
```

## Parameters

| Parameter | Type | Default | Meaning |
| --- | --- | --- | --- |
| `selector` | CSS selector | required | Which direct children to include (`child.matches(selector)`) |
| `attributes` | `string[]` | `[]` | Attribute names to watch on the children and their descendants |

## Updates

The array is refreshed when:

- children are added, removed or reordered (anywhere in the light DOM subtree),
- text inside them changes,
- one of the listed `attributes` changes on a descendant,
- a child REALM component finishes mounting, so its props can be read.

Watching stops when the element is removed.

## Example

```html live
<custom-element name="option-count">
  <script type="realm">
    const options = useChildren("option", ["disabled"]);
    const view = useState({
      get enabled() {
        return options.filter((option) => !option.disabled).map((option) => option.textContent).join(", ");
      },
    });

    function toggleLast() {
      host.lastElementChild.toggleAttribute("disabled");
    }
  </script>

  <p>Enabled: <slot name="#view.enabled"></slot></p>
  <ui-button variant="outline" onclick="toggleLast()">Toggle the last option</ui-button>
</custom-element>

<option-count>
  <option>Small</option>
  <option>Medium</option>
  <option>Large</option>
</option-count>
```

## Related

- [`useChildren` in REALM UI's select and tabs](/components/)


---

# `defineMethods`

Source: http://realm.js.org/reference/script/define-methods/

Copies methods, getters and setters onto the element, so outside code can call `element.method()`.

```ts
defineMethods(methods: object): void
```

```js
defineMethods({
  open() {
    panel.open = true;
  },
  close() {
    panel.open = false;
  },
  get isOpen() {
    return panel.open;
  },
});
```

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `methods` | object | Every own property (including getters and setters) is defined on the element with the same descriptor, made configurable |

The properties are removed when the element is removed. Call `defineMethods` after your functions and before lifecycle hooks.

## Example

```html live
<custom-element name="step-counter">
  <script type="realm">
    const counter = useState({ value: 0 });

    defineMethods({
      increment() {
        counter.value++;
      },
      get value() {
        return counter.value;
      },
    });
  </script>

  <p>Value: <slot name="#counter.value"></slot></p>
</custom-element>

<step-counter id="steps"></step-counter>
<ui-button variant="outline" onclick="document.getElementById('steps').increment()">Call steps.increment()</ui-button>
```

## Related

- [Events: public methods](/docs/events/#public-methods)


---

# `dispatch`

Source: http://realm.js.org/reference/script/dispatch/

Sends a `CustomEvent` from the host.

```ts
dispatch(type: string, detail?: unknown, options?: CustomEventInit): boolean
```

```js
function select(item) {
  if (dispatch("select", { id: item.id })) state.selected = item.id;
}
```

## Parameters

| Parameter | Type | Default | Meaning |
| --- | --- | --- | --- |
| `type` | `string` | required | Event name |
| `detail` | any | `undefined` | `event.detail` |
| `options` | `CustomEventInit` | `{ bubbles: true, composed: true, cancelable: true }` | Overrides any of the defaults |

Returns `false` if a listener called `preventDefault()` (or a handler attribute returned `false`), otherwise `true`.

## Handling the event

| Where | How |
| --- | --- |
| A parent component's markup | `<child-tag onselect="choose(event.detail)">` |
| A plain page | `<child-tag onselect="…">` or `element.onselect = fn`. REALM finds names written as `dispatch("name"` in the script. See [`on…` handlers](/reference/attributes/handlers/#on-a-plain-page) |
| JavaScript | `element.addEventListener("select", …)` |

## Example

```html live
<custom-element name="color-picker">
  <script type="realm">
    function pick(color) {
      dispatch("pick", { color });
    }
  </script>

  <style type="realm">
    :host {
      display: inline-flex;
      gap: calc(var(--spacing) * 2);
    }
  </style>

  <ui-button variant="outline" onclick="pick('red')">Red</ui-button>
  <ui-button variant="outline" onclick="pick('green')">Green</ui-button>
  <ui-button variant="outline" onclick="pick('blue')">Blue</ui-button>
</custom-element>

<color-picker onpick="document.getElementById('picked').value = event.detail.color"></color-picker>
<output id="picked">none</output>
```

## Related

- [Events: emitting events](/docs/events/#emitting-events)
- [Component events](/reference/events/component-events/)


---

# `listen`

Source: http://realm.js.org/reference/script/listen/

Adds an event listener that is removed when the element is removed.

```ts
listen(type: string, handler: (event: Event) => unknown, target?: EventTarget): void
```

```js
listen("keydown", onKey);
listen("resize", layout, window);
listen("visibilitychange", pause, document);
```

## Parameters

| Parameter | Type | Default | Meaning |
| --- | --- | --- | --- |
| `type` | `string` | required | Event name |
| `handler` | `(event) => unknown` | required | Listener |
| `target` | `EventTarget` | `host` | Where to listen |

Same as `target.addEventListener(type, handler, { signal })` with the element's [`signal`](/reference/script/signal/). The return value of `handler` is ignored (use `event.preventDefault()` to cancel).

## Example

```html live
<custom-element name="key-display">
  <script type="realm">
    const keys = useState({ last: "" });

    listen("keydown", (event) => {
      keys.last = event.key;
    }, window);
  </script>

  <p>Last key pressed anywhere: <kbd><slot name="#keys.last">none</slot></kbd></p>
</custom-element>

<key-display></key-display>
```

## Related

- [Events: listening from the script](/docs/events/#listening-from-the-script)


---

# `lookup`

Source: http://realm.js.org/reference/script/lookup/

Returns a name from the nearest parent component that defines it, or from `globalThis`.

```ts
lookup(name: string): unknown
```

```js
const session = lookup("session");
```

## Behaviour

| Step | Source |
| --- | --- |
| 1 | Parent components, nearest first, walking up through shadow roots. A component "defines" a name when it is a top-level name of its script |
| 2 | `globalThis[name]` |

When a parent provides the name, REALM logs `<child> reads "name" from <parent>.` once (not for [compound parts](/reference/elements/custom-element/#slot)). Handlers use the same lookup, at call time, for names the script does not define.

Use props for data a reusable component depends on. Use `lookup` for small parts that always live inside one parent.

## Example

```html live
<custom-element name="theme-shell">
  <script type="realm">
    const theme = useState({ accent: "Blue" });
  </script>

  <theme-label></theme-label>
  <ui-button variant="outline" onclick="theme.accent = theme.accent === 'Blue' ? 'Green' : 'Blue'">Switch</ui-button>
</custom-element>

<custom-element name="theme-label">
  <script type="realm">
    const theme = lookup("theme");
  </script>

  <p>Accent from the parent: <slot name="#theme.accent"></slot></p>
</custom-element>

<theme-shell></theme-shell>
```

`theme-label` reads the parent's state once with `lookup`. The object it gets is reactive, so the slot stays up to date.

## Related

- [Nested components and scope](/docs/scope/)


---

# Timers

Source: http://realm.js.org/reference/script/timers/

Inside a component script, `setTimeout`, `setInterval`, `clearTimeout` and `clearInterval` are bound to the element. Any timer still pending when the element is removed is cleared.

```ts
setTimeout(callback: (...args: unknown[]) => void, delay?: number, ...args: unknown[]): number
setInterval(callback: (...args: unknown[]) => void, delay?: number, ...args: unknown[]): number
clearTimeout(id?: number): void
clearInterval(id?: number): void
```

```js
const clock = useState({ now: new Date() });
setInterval(() => (clock.now = new Date()), 1000);
```

## Behaviour

| Topic | Detail |
| --- | --- |
| Signature | The same as `window.setTimeout` / `window.setInterval`, returning the same numeric ids |
| Cleanup | Pending timeouts and all intervals are cleared when the element's [`signal`](/reference/script/signal/) aborts |
| Clearing | `clearTimeout` and `clearInterval` both work for either kind of id |
| Window timers | `window.setTimeout(…)` is still available and is **not** cleared automatically |

These versions apply only inside the component script and its handlers. Modules imported by the script use the normal globals.

## Example

```html live
<custom-element name="live-clock">
  <script type="realm">
    const clock = useState({ time: new Date().toLocaleTimeString() });

    setInterval(() => {
      clock.time = new Date().toLocaleTimeString();
    }, 1000);
  </script>

  <p>The time is <time><slot name="#clock.time"></slot></time>.</p>
</custom-element>

<live-clock></live-clock>
```

## Related

- [Performance and memory: memory and cleanup](/docs/performance/#memory-and-cleanup)


---

# `onConnected`

Source: http://realm.js.org/reference/script/on-connected/

Runs a function after the component's markup is in its shadow root and [`refs`](/reference/script/refs/) are filled.

```ts
onConnected(fn: () => unknown): void
```

```js
onConnected(() => {
  const chart = new Chart(refs.canvas, config);
  return () => chart.destroy();
});
```

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `fn` | `() => unknown` | Runs once, after the first connection. If it returns a function, that function runs when the element is removed |

## Order on connection

1. The script runs (`defineProps`, `useState`, …).
2. Reactive CSS is bound.
3. The markup is cloned, bound and appended to the shadow root, and `refs` fill.
4. A delegated `ref="control"` is wired up.
5. The parent's [`useChildren`](/reference/script/use-children/) arrays refresh.
6. `onConnected` hooks run in the order they were registered.

Moving the element does not run the hooks again. It keeps its state.

## Example

```html live
<custom-element name="auto-focus">
  <script type="realm">
    onConnected(() => {
      refs.field.placeholder = "Filled in by onConnected";
    });
  </script>

  <input ref="field" aria-label="Example field">
</custom-element>

<auto-focus></auto-focus>
```

## Related

- [Lifecycle](/docs/lifecycle/)


---

# `onDisconnected`

Source: http://realm.js.org/reference/script/on-disconnected/

Runs a function when the element is removed.

```ts
onDisconnected(fn: () => void): void
```

```js
onDisconnected(() => {
  socket.close();
});
```

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `fn` | `() => void` | Runs once when the element is removed |

## Order on removal

REALM waits one microtask after `disconnectedCallback`. If the element is connected again by then (it was moved), nothing happens. Otherwise:

1. `onDisconnected` hooks run in the order they were registered.
2. [`signal`](/reference/script/signal/) aborts: listeners, requests, timers and debounced calls stop.
3. Observers stop, cleanups returned from `onConnected` and `observe` run, prop accessors and [`defineMethods`](/reference/script/define-methods/) are removed.
4. The shadow root is emptied.

Adding the element again later creates a fresh instance: the script runs again.

## Example

```html live
<custom-element name="goodbye-note">
  <script type="realm">
    onDisconnected(() => {
      document.getElementById("goodbye-log").value = `Removed at ${new Date().toLocaleTimeString()}`;
    });
  </script>

  <p>I will log when I am removed.</p>
</custom-element>

<custom-element name="goodbye-host">
  <script type="realm">
    const view = useState({ shown: true });
  </script>

  <is-visible when="#view.shown"><goodbye-note></goodbye-note></is-visible>
  <ui-button variant="outline" onclick="view.shown = !view.shown">Toggle the note</ui-button>
</custom-element>

<goodbye-host></goodbye-host>
<output id="goodbye-log">Not removed yet.</output>
```

## Related

- [Lifecycle: when an element is removed](/docs/lifecycle/#when-an-element-is-removed)


---

# `onFormReset`

Source: http://realm.js.org/reference/script/on-form-reset/

Runs when the owning form is reset. For components defined with [`form-associated`](/reference/elements/custom-element/#form-associated).

```ts
onFormReset(fn: () => void): void
```

```js
onFormReset(() => {
  editor.text = "";
});
```

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `fn` | `() => void` | Runs from the element's `formResetCallback` |

Before your hooks run, REALM re-reads every declared prop from its attribute, so props with an attribute go back to their initial values automatically. Use this hook for state that is not a prop.

## Example

```html live
<custom-element name="tally-field" form-associated>
  <script type="realm">
    const props = defineProps({ value: prop.number().default(0) });

    onFormReset(() => {
      document.getElementById("reset-log").value = "Reset ran";
    });
  </script>

  <ui-button variant="outline" onclick="props.value++">Tally: <slot name="@value"></slot></ui-button>
</custom-element>

<form>
  <tally-field name="tally"></tally-field>
  <ui-button type="reset" variant="ghost">Reset</ui-button>
  <output id="reset-log"></output>
</form>
```

## Related

- [Forms: form lifecycle hooks](/docs/forms/#form-lifecycle-hooks)


---

# `onFormDisabled`

Source: http://realm.js.org/reference/script/on-form-disabled/

Runs when the element becomes disabled or enabled, either through its own `disabled` attribute or a surrounding `<fieldset disabled>`. For components defined with [`form-associated`](/reference/elements/custom-element/#form-associated).

```ts
onFormDisabled(fn: (disabled: boolean) => void): void
```

```js
onFormDisabled((disabled) => {
  refs.control.tabIndex = disabled ? -1 : 0;
});
```

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `fn` | `(disabled: boolean) => void` | Runs from the element's `formDisabledCallback` with the new state |

You often do not need it. With a `disabled` prop, `props.disabled` already reads `true` while a fieldset disables the element, and the component starts disabled when it is created inside one.

## Example

```html live
<custom-element name="disable-aware" form-associated>
  <script type="realm">
    const status = useState({ text: "enabled" });

    onFormDisabled((disabled) => {
      status.text = disabled ? "disabled" : "enabled";
    });
  </script>

  <p>I am <slot name="#status.text"></slot>.</p>
</custom-element>

<fieldset id="disable-set">
  <legend>Fieldset</legend>
  <disable-aware></disable-aware>
</fieldset>
<ui-button variant="outline" onclick="document.getElementById('disable-set').toggleAttribute('disabled')">Toggle fieldset disabled</ui-button>
```

## Related

- [Forms: disabled fields](/docs/forms/#disabled-fields)


---

# `onFormStateRestore`

Source: http://realm.js.org/reference/script/on-form-state-restore/

Runs when the browser restores the element's state, after back/forward navigation or autofill. For components defined with [`form-associated`](/reference/elements/custom-element/#form-associated).

```ts
onFormStateRestore(fn: (state: unknown, mode: string) => void): void
```

```js
onFormStateRestore((state, mode) => {
  editor.text = String(state ?? "");
});
```

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `fn` | `(state, mode) => void` | Runs from the element's `formStateRestoreCallback` |
| `state` | `unknown` | The value saved with `setFormValue` (a string, `File`, `FormData` or `null`) |
| `mode` | `"restore"` or `"autocomplete"` | Why the state is restored |

When the component declares a `value` prop, REALM already writes `state` to it (or sets `checked` to `state !== null` when it declares `checked`) before your hooks run.

## Related

- [Forms](/docs/forms/)
- [`internals`](/reference/script/internals/)


---

# Request events

Source: http://realm.js.org/reference/events/request-events/

Fired on the element that has the [fetch attributes](/reference/fetch/fetch/). They do **not** bubble, so handle them on that element: `onload="…"` in component markup, or `addEventListener`.

```html
<button fetch="/api/items" into="#list.items" onload="notify(event.detail.status)" onerror="fail(event.detail)">Load</button>
```

## Events

| Event | Cancelable | When | `detail` |
| --- | --- | --- | --- |
| `loadstart` | yes | Before the request is sent. `preventDefault()` (or `return false` in a handler) stops it | `{ url: string, method: string }` |
| `load` | no | A 2xx response, after `into` and `render` were applied | `{ status: number, data: unknown, headers: Headers, url: string }` |
| `error` | no | A non-2xx response | `{ status: number, data: unknown, headers: Headers, url: string }` |
| `error` | no | A network failure | `{ status: 0, data: undefined, message: string, url: string }` |
| `abort` | no | A newer request from the same element replaced this one, or the element was removed | `{ url: string }` |
| `timeout` | no | The [`timeout`](/reference/fetch/busy-timeout/) elapsed | `{ url: string }` |
| `loadend` | no | After every request that started, whatever the outcome | `{ url: string }` |

`data` is the parsed JSON when the response's `Content-Type` contains `json`, otherwise the response text. `url` in `load` and `error` is the final response URL after redirects. In the other events it is the request URL including the query string.

## Order

```text
loadstart → (load | error | abort | timeout) → loadend
```

A cancelled `loadstart` sends nothing and fires nothing else.

## Example

```html live
<custom-element name="event-log">
  <script type="realm">
    const log = useState({ lines: [] });

    function note(event) {
      log.lines.push(`${event.type}${event.detail.status ? ` ${event.detail.status}` : ""}`);
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      justify-items: start;
    }
    ol {
      margin: 0;
    }
  </style>

  <ui-button fetch="/search-index.json" onloadstart="note(event)" onload="note(event)" onloadend="note(event)">Send a request</ui-button>
  <ol><li repeat="#log.lines" as="line"><slot name="#line"></slot></li></ol>
</custom-element>

<event-log></event-log>
```

## Related

- [Fetching data: events](/docs/fetching/#events)


---

# Import events

Source: http://realm.js.org/reference/events/import-events/

Fired on [`<import-element>`](/reference/elements/import-element/). They do not bubble.

| Event | When | `detail` |
| --- | --- | --- |
| `load` | Every `<custom-element>` in the file has been defined | `{ url: string }` |
| `error` | The file could not be fetched (non-2xx or network failure) | `{ url: string, status: number }` |

- `url` is the absolute URL of the file.
- `status` is the HTTP status, or `0` for a network error.
- Neither event fires if the element was removed before the file arrived.
- A failure also logs `Could not import URL (HTTP status)`.

```html
<import-element from="/components/charts.html" onload="console.log('ready', event.detail.url)" onerror="showFallback(event.detail.status)"></import-element>
```

`onload` and `onerror` are native handler attributes, so they work on a plain page too.

See the live example on [`<import-element>`](/reference/elements/import-element/#example-lazy-loading-and-the-load-event).

## Related

- [Importing components: events](/docs/importing/#events)


---

# Component events

Source: http://realm.js.org/reference/events/component-events/

Components send their own events. REALM adds one event of its own for form-associated components.

## Sending

| Way | Defaults |
| --- | --- |
| [`dispatch(type, detail, options)`](/reference/script/dispatch/) | `bubbles: true`, `composed: true`, `cancelable: true` |
| `host.dispatchEvent(new CustomEvent(type, init))` | Whatever `init` says |

Composed events cross shadow boundaries, so a page can listen on an ancestor.

## Handling

| Where | How |
| --- | --- |
| A parent component's markup | `on<type>="code"` on the child, for any event name. See [`on…` handlers](/reference/attributes/handlers/) |
| A plain page | `on<type>="code"` attribute or `element.on<type> = fn` property, for event names found in the component's script |
| Anywhere | `addEventListener(type, …)` |

On plain pages, REALM finds event names written as `dispatch("name"`, `new CustomEvent("name"` or `new Event("name"` in the component script. Names that are native handlers (`onchange`, `oninput`, `onclose`, …) already work and are not redefined.

## change from delegated controls

A form-associated component with [`ref="control"`](/reference/attributes/ref/#ref-control) re-dispatches its control's `change` event from the host:

| Event | Bubbles | Composed | When |
| --- | --- | --- | --- |
| `change` | yes | no | The inner control fired `change`, after the `value` / `checked` prop was updated |

The inner control's own `input` events are composed and reach the host's listeners as they are.

## REALM UI events

Each component page under [Components](/components/) lists that component's events.

## Related

- [Events](/docs/events/)


---

# `realm.css`

Source: http://realm.js.org/reference/css/realm-css/

A small page stylesheet. Load it in the `<head>`, before anything renders:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css">
```

## Contents

```css
custom-element,
import-element {
  display: none;
}

is-visible,
is-hidden,
repeat-list {
  display: contents;
}

:not(:defined) {
  visibility: hidden;
}
```

| Rule | Why |
| --- | --- |
| `custom-element, import-element { display: none }` | Definitions and import tags never show |
| `is-visible, is-hidden, repeat-list { display: contents }` | Control-flow tags add no box, so they do not break flex or grid layouts |
| `:not(:defined) { visibility: hidden }` | Custom elements stay invisible until they are defined, so the page never shows unstyled component content. They keep their space, so layout does not jump |

## Added by REALM

Even without `realm.css`, REALM adds these rules itself.

| Where | Rules |
| --- | --- |
| The page, when [`start()`](/reference/javascript/start/) runs | `custom-element, import-element { display: none !important }` and the `display: contents` rule, as an adopted stylesheet |
| Every component's shadow root (first adopted sheet) | `is-visible, is-hidden, repeat-list { display: contents }` and `:host([hidden]) { display: none !important }` |

The `:host([hidden])` rule makes the `hidden` attribute hide a component even when its styles set `:host { display: flex }`. The `:not(:defined)` rule is only in `realm.css`, because it has to apply before any script runs.

## Related

- [Installation](/docs/installation/)
- [Styling](/docs/styling/)


---

# `--attr-*` and `--state-*`

Source: http://realm.js.org/reference/css/variables/

Write `var(--attr-…)` or `var(--state-…)` in a component's `<style>` and REALM keeps that custom property set on the host, from a prop, an attribute or state.

```css
:host {
  --size: var(--attr-size, 1);
  width: calc(var(--spacing) * 10 * var(--size));
}
.bar {
  width: calc(var(--state-upload-percent, 0) * 1%);
}
```

## Names

| Variable | Value |
| --- | --- |
| `var(--attr-name)` | The prop whose attribute is `name` (its current value, not the attribute text), or the host attribute `name` when no prop uses it |
| `var(--state-a-b-c)` | The reference `#a.b.c`. Dashes separate path segments |

Because dashes separate segments, script and state names used in `--state-*` cannot contain dashes. camelCase works: `var(--state-todo-doneCount)`. Attribute names in `--attr-*` can contain dashes: `var(--attr-max-items)`.

## Values

| Value | Set to |
| --- | --- |
| string, number, boolean | `String(value)` |
| `null`, `undefined`, object, array | `initial`, so `var(--attr-x, fallback)` uses the fallback |

## Behaviour

- REALM finds the variables by scanning the text of the component's `<style>` and `<link rel="stylesheet">` elements, so only names written there are set.
- They are set as inline custom properties on the host and update when the value changes.
- Each component sets its own variables on its own host, so `--attr-*` values do not leak into nested components that use the same names.
- To set a custom property on an inner element instead, bind it: `_--progress="#upload.percent"`. See [`_` bindings](/reference/attributes/bindings/).

## Example

```html live
<custom-element name="progress-pill">
  <script type="realm">
    const props = defineProps({ tone: prop.enum(["primary", "destructive"]).default("primary") });
    const upload = useState({ percent: 30 });
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      width: min(calc(var(--spacing) * 80), 100%);
    }
    .track {
      height: calc(var(--spacing) * 3);
      border-radius: var(--radius-full);
      background: var(--muted);
    }
    .fill {
      height: 100%;
      width: calc(var(--state-upload-percent, 0) * 1%);
      border-radius: inherit;
      background: var(--primary);
    }
    :host(:state(attr-tone-is-destructive)) .fill {
      background: var(--destructive);
    }
  </style>

  <div class="track"><div class="fill"></div></div>
  <input type="range" aria-label="Percent" min="0" max="100" _value="#upload.percent" oninput="upload.percent = Number(this.value)">
</custom-element>

<progress-pill></progress-pill>
<progress-pill tone="destructive"></progress-pill>
```

## Related

- [Styling: reactive CSS](/docs/styling/#reactive-css)
- [`:state()`](/reference/css/states/)


---

# `:state()`

Source: http://realm.js.org/reference/css/states/

Write `:state(attr-…)` or `:state(state-…)` in a component's `<style>` and REALM adds or removes that custom state on the host, through `internals.states`. Match it with `:host(:state(…))` inside the component, or `tag-name:state(…)` from the page.

```css
:host(:state(attr-variant-is-outline)) {
  border: 1px solid var(--border);
}
:host(:state(state-todo-remaining-gt-0)) .clear {
  display: none;
}
```

## States

| State | Present while |
| --- | --- |
| `attr-name` | The prop or attribute `name` is truthy |
| `attr-name-is-value` | It equals `value` (compared as text) |
| `attr-name-gt-n` | It is greater than `n` (as numbers) |
| `attr-name-gte-n` | Greater than or equal to `n` |
| `attr-name-lt-n` | Less than `n` |
| `attr-name-lte-n` | Less than or equal to `n` |
| `state-a-b` | The reference `#a.b` is truthy |
| `state-a-b-is-value`, `-gt-n`, `-gte-n`, `-lt-n`, `-lte-n` | The same comparisons on `#a.b` |
| `loading` | A fetch attribute request in the component is running |

`attr-…` reads the prop's value when a prop uses that attribute, otherwise the attribute text (an absent attribute is `null`, so it is falsy). As with [`--state-*`](/reference/css/variables/), dashes separate path segments in `state-…`, so use camelCase names.

REALM finds these states by scanning the text of the component's `<style>` and `<link rel="stylesheet">` elements. Only names written there are maintained.

## loading

`:state(loading)` is present while at least one request started by [fetch attributes](/reference/fetch/fetch/) in the component's markup is running. The fetch element itself also gets `aria-busy="true"`.

```css
:host(:state(loading)) .results {
  opacity: 0.5;
}
```

## Your own states

Add any other state from the script and match it the same way:

```js
internals.states.add("expanded");
internals.states.delete("expanded");
```

```css
:host(:state(expanded)) .details {
  display: block;
}
```

## Example

```html live
<custom-element name="level-badge">
  <script type="realm">
    const props = defineProps({ level: prop.number().int().min(0).max(10).default(0) });
  </script>

  <style type="realm">
    :host {
      display: inline-block;
      padding: calc(var(--spacing) * 1) calc(var(--spacing) * 3);
      border-radius: var(--radius-full);
      background: var(--muted);
      font-size: var(--text-sm);
    }
    :host(:state(attr-level-gte-5)) {
      background: var(--chart-4);
      color: var(--primary);
    }
    :host(:state(attr-level-gte-8)) {
      background: var(--destructive);
      color: var(--primary-foreground);
    }
  </style>

  Level <slot name="@level"></slot>
</custom-element>

<level-badge level="2"></level-badge>
<level-badge level="6"></level-badge>
<level-badge level="9"></level-badge>
```

## Related

- [Styling: states](/docs/styling/#states-state-attr-and-state-state)
- [`internals`](/reference/script/internals/)


---

# Design tokens

Source: http://realm.js.org/reference/css/design-tokens/

The `@realmorg/ui` theme defines colour, spacing, type, radius, shadow and motion tokens as custom properties on `:root`. REALM UI components use them. Use them in your own components too, so sizes and colours match and theming works.

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/theme.css">
```

Custom properties inherit through shadow roots, so a token on `:root` reaches every component.

```css
:host {
  padding: calc(var(--spacing) * 4);
  border-radius: var(--radius-md);
  font-size: var(--text-sm);
  box-shadow: var(--shadow-sm);
  color: var(--card-foreground);
  background: var(--card);
}
```

## Spacing

| Token | Value | Use |
| --- | --- | --- |
| `--spacing` | `0.25rem` | Base unit. Write sizes as `calc(var(--spacing) * n)` |

## Type

| Token | Value |
| --- | --- |
| `--text-xs` | `0.75rem` |
| `--text-sm` | `0.875rem` |
| `--text-base` | `1rem` |
| `--text-lg` | `1.125rem` |
| `--text-xl` | `1.25rem` |
| `--text-2xl` | `1.5rem` |
| `--text-3xl` | `1.875rem` |
| `--text-4xl` | `2.25rem` |
| `--leading-tight` | `1.25` |
| `--leading-normal` | `1.5` |
| `--font-weight-normal` | `400` |
| `--font-weight-medium` | `500` |
| `--font-weight-semibold` | `600` |
| `--font-weight-bold` | `700` |
| `--tracking-tight` | `-0.025em` |
| `--font-sans` | `ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif` |
| `--font-mono` | `ui-monospace, "SF Mono", Menlo, monospace` |

## Radius

| Token | Value |
| --- | --- |
| `--radius` | `0.625rem` (the base the others derive from) |
| `--radius-xs` | `calc(var(--radius) - 6px)` |
| `--radius-sm` | `calc(var(--radius) - 4px)` |
| `--radius-md` | `calc(var(--radius) - 2px)` |
| `--radius-lg` | `var(--radius)` |
| `--radius-xl` | `calc(var(--radius) + 4px)` |
| `--radius-2xl` | `calc(var(--radius) + 8px)` |
| `--radius-full` | `9999px` |

## Shadow and focus

| Token | Value |
| --- | --- |
| `--shadow-xs` | `0 1px 2px 0 rgb(0 0 0 / 0.05)` |
| `--shadow-sm` | `0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)` |
| `--shadow-md` | `0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)` |
| `--shadow-lg` | `0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)` |
| `--focus-ring` | `0 0 0 3px` of `--ring` at 50%. Use as `box-shadow` on `:focus-visible` |

## Motion

| Token | Value |
| --- | --- |
| `--default-transition-duration` | `150ms` |
| `--default-transition-timing-function` | `cubic-bezier(0.4, 0, 0.2, 1)` |

## Colour

Each surface colour has a matching `-foreground` for text on it.

| Token | Use |
| --- | --- |
| `--background`, `--foreground` | Page |
| `--card`, `--card-foreground` | Cards and panels |
| `--popover`, `--popover-foreground` | Popovers, menus, tooltips |
| `--primary`, `--primary-foreground` | Main actions |
| `--secondary`, `--secondary-foreground` | Secondary actions |
| `--muted`, `--muted-foreground` | Subdued surfaces and text |
| `--accent`, `--accent-foreground` | Hover and selected states |
| `--destructive`, `--destructive-foreground` | Dangerous actions and errors |
| `--border` | Borders and separators |
| `--input` | Form field borders |
| `--ring` | Focus rings |
| `--chart-1` … `--chart-5` | Data series |
| `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-border`, `--sidebar-ring` | Sidebar navigation |

Colours are written in `oklch()`. The values differ between light and dark mode. See `theme.css` for the exact numbers.

## Dark mode

| Condition | Colours |
| --- | --- |
| `<html data-theme="dark">` | Dark |
| `<html data-theme="light">` | Light |
| no `data-theme`, system prefers dark | Dark |
| otherwise | Light |

`theme.css` also sets `color-scheme` and gives `body` the `--background`, `--foreground` and `--font-sans` values.

## Example

```html live
<custom-element name="token-swatches">
  <style type="realm">
    :host {
      display: flex;
      flex-wrap: wrap;
      gap: calc(var(--spacing) * 2);
    }
    span {
      padding: calc(var(--spacing) * 2) calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      font-size: var(--text-sm);
      box-shadow: var(--shadow-xs);
    }
    .primary { background: var(--primary); color: var(--primary-foreground); }
    .secondary { background: var(--secondary); color: var(--secondary-foreground); }
    .muted { background: var(--muted); color: var(--muted-foreground); }
    .accent { background: var(--accent); color: var(--accent-foreground); }
    .destructive { background: var(--destructive); color: var(--destructive-foreground); }
  </style>

  <span class="primary">primary</span>
  <span class="secondary">secondary</span>
  <span class="muted">muted</span>
  <span class="accent">accent</span>
  <span class="destructive">destructive</span>
</custom-element>

<token-swatches></token-swatches>
```

## Related

- [Styling: design tokens](/docs/styling/#design-tokens)
- [Styling: theming and dark mode](/docs/styling/#theming-and-dark-mode)


---

# Entry points

Source: http://realm.js.org/reference/javascript/entry-points/

REALM ships as ES modules. Load them from the CDN, and pin an exact version in production.

| File | Package export | Purpose |
| --- | --- | --- |
| `https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js` | `@realmorg/realm/auto` | Calls [`start()`](/reference/javascript/start/) when it loads, and exports the API |
| `https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/index.js` | `@realmorg/realm` | The same API without starting. No side effects |
| `https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/compiler.js` | `@realmorg/realm/compiler` | Build-time helpers. See [Compiler](/reference/javascript/compiler/) |
| `https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css` | `@realmorg/realm/realm.css` | The page stylesheet. See [realm.css](/reference/css/realm-css/) |

`realm.js` and `index.js` share one runtime chunk, so a page that starts REALM with `realm.js` and a module that imports from `index.js` (same version) use the same stores and definitions.

## Starting REALM

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js"></script>
```

Or start it yourself after other setup:

```html
<script type="module">
  import { start } from "https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/index.js";

  start();
</script>
```

## Exports

`realm.js` and `index.js` export the same names:

| Export | Signature | Page |
| --- | --- | --- |
| `start` | `start(): void` | [start](/reference/javascript/start/) |
| `importDefinitions` | `importDefinitions(url: string): Promise<void>` | [importDefinitions](/reference/javascript/import-definitions/) |
| `defineComponent` | `defineComponent(element: Element, base: string, inline: boolean): Promise<void>` | [defineComponent](/reference/javascript/define-component/) |
| `useState` | `useState<T extends object>(initial: T): T` | [useState](/reference/script/use-state/) |
| `observe` | `observe(fn: () => unknown): () => void` | [observe](/reference/script/observe/). Not tied to an element when imported |
| `defineStore` | `defineStore<T extends object>(name: string, initial: T, options?: StoreOptions): T` | [defineStore](/reference/script/define-store/) |
| `prop` | `{ string, number, boolean, enum, date, array, object }` | [prop](/reference/script/prop/) |
| `flush` | `flush(): void` | [flush](/reference/javascript/flush/) |
| `toRaw` | `toRaw<T>(value: T): T` | [toRaw](/reference/javascript/to-raw/) |
| `untrack` | `untrack<T>(fn: () => T): T` | [untrack](/reference/javascript/untrack/) |

Types (for TypeScript users of the package): `Context` (the [script helpers](/reference/script/)), `StoreOptions` and `StorageAdapter`.

## Bare specifiers in component scripts

A component script that writes `import { defineStore } from "@realmorg/realm"` needs an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap). Point it at the file the page uses to start REALM:

```html
<script type="importmap">
  { "imports": { "@realmorg/realm": "https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js" } }
</script>
```

## Related

- [Installation](/docs/installation/)


---

# Button

Source: http://realm.js.org/components/button/

`ui-button` wraps a native `<button>` in its shadow root and adds visual variants and sizes. It is form-associated.
With `type="submit"` or `type="reset"` it submits or resets the form it sits in, even though the inner button lives
in a shadow root. It also forwards the native invoker attributes `popovertarget`, `commandfor` and `command`, so it
can open popovers and dialogs without script.

Unlike a native `<button>`, the default `type` is `button`, so a `ui-button` inside a form does nothing until you
set `type="submit"` or `type="reset"`.

```html live
<ui-button>Button</ui-button>
```

## Examples

### Variants

Set `variant` to `default`, `destructive`, `outline`, `secondary`, `ghost` or `link`.

```html live
<ui-button>Default</ui-button>
<ui-button variant="secondary">Secondary</ui-button>
<ui-button variant="destructive">Destructive</ui-button>
<ui-button variant="outline">Outline</ui-button>
<ui-button variant="ghost">Ghost</ui-button>
<ui-button variant="link">Link</ui-button>
```

### Sizes

Text buttons come in `xs`, `sm`, `default` and `lg`.

```html live
<ui-button size="xs">Extra small</ui-button>
<ui-button size="sm">Small</ui-button>
<ui-button>Default</ui-button>
<ui-button size="lg">Large</ui-button>
```

### Icon buttons

The `icon`, `icon-xs`, `icon-sm` and `icon-lg` sizes make a square button. A slotted `<svg>` is sized to the button
text. Give icon-only buttons an accessible name with `aria-label`.

```html live
<ui-button variant="outline" size="icon-xs" aria-label="Add">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M12 5v14M5 12h14" /></svg>
</ui-button>
<ui-button variant="outline" size="icon-sm" aria-label="Add">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M12 5v14M5 12h14" /></svg>
</ui-button>
<ui-button variant="outline" size="icon" aria-label="Add">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M12 5v14M5 12h14" /></svg>
</ui-button>
<ui-button variant="outline" size="icon-lg" aria-label="Add">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M12 5v14M5 12h14" /></svg>
</ui-button>
```

### With an icon

Put an `<svg>` before or after the label. The button adds a gap between them.

```html live
<ui-button>
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M4 12v8h16v-8M12 3v12M7 8l5-5 5 5" /></svg>
  Upload
</ui-button>
<ui-button variant="outline">
  Next
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m9 18 6-6-6-6" /></svg>
</ui-button>
```

### Loading

Combine `disabled` with a `ui-spinner` while work is in progress.

```html live
<ui-button disabled><ui-spinner size="14"></ui-spinner> Saving</ui-button>
```

### Disabled

`disabled` disables the inner button and reflects to the host, so `ui-button[disabled]` can be styled from outside.

```html live
<ui-button disabled>Disabled</ui-button>
<ui-button variant="outline" disabled>Disabled</ui-button>
```

### In a form

`type="submit"` submits the surrounding form and `type="reset"` resets it. Buttons inside a disabled `<fieldset>` are
disabled too.

```html live
<custom-element name="button-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      const entries = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`);
      result.text = entries.join("\n") || "(no fields)";
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-input name="title" value="Quarterly report" aria-label="Title"></ui-input>
    <div class="actions">
      <ui-button type="submit">Save</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<button-form-demo></button-form-demo>
```

### Open a popover

`popovertarget` and `popovertargetaction` work as on a native button. The target is looked up by id in the same
document or shadow root.

```html live
<ui-button variant="outline" popovertarget="button-popover">Toggle popover</ui-button>
<div id="button-popover" popover>Opened from a ui-button.</div>
```

### Invoke a command

`commandfor` and `command` are the native invoker commands. Browsers without native support get the same
behaviour. The button dispatches a cancelable `command` event on the target and then calls `showModal()`, `close()`,
`requestClose()`, `togglePopover()`, `showPopover()` or `hidePopover()`. When the target is a component such as
`ui-dialog` rather than a native `<dialog>`, `show-modal`, `close` and `request-close` are sent as `--show-modal`,
`--close` and `--request-close`, because browsers only deliver built-in dialog commands to native dialogs.

```html live
<ui-button commandfor="button-dialog" command="show-modal">Open dialog</ui-button>
<dialog id="button-dialog">
  <p>This dialog was opened with commandfor.</p>
  <ui-button variant="outline" commandfor="button-dialog" command="close">Close</ui-button>
</dialog>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default"` \| `"destructive"` \| `"outline"` \| `"secondary"` \| `"ghost"` \| `"link"` | `"default"` | Visual style. |
| `size` | `"default"` \| `"xs"` \| `"sm"` \| `"lg"` \| `"icon"` \| `"icon-xs"` \| `"icon-sm"` \| `"icon-lg"` | `"default"` | Height and padding. The `icon` sizes make a square button. |
| `type` | `"button"` \| `"submit"` \| `"reset"` | `"button"` | What the button does in its form. |
| `disabled` | boolean | `false` | Disables the button. Reflects to the attribute. Also true while the button is inside a disabled `<fieldset>`. |
| `aria-label` | string | | Accessible name, passed to the inner button. Use it for icon-only buttons. Property name: `label`. |
| `aria-description` | string | | Accessible description, passed to the inner button. `ui-tooltip` sets it from its content. Property name: `description`. |
| `popovertarget` | string | | Id of a popover element to toggle. |
| `popovertargetaction` | `"toggle"` \| `"show"` \| `"hide"` | | Action taken on the popover target. |
| `commandfor` | string | | Id of the element that receives `command`. |
| `command` | string | | Command to invoke, such as `show-modal`, `close`, `request-close`, `toggle-popover`, `show-popover`, `hide-popover` or a custom `--command`. |

### Events

`ui-button` dispatches no events of its own. Listen for `click` as on any element. When native invoker commands are
not supported, the button dispatches a cancelable `command` event on the `commandfor` target with `command` and
`source` properties. Calling `preventDefault()` stops the built-in action.

### Slots

| Slot | Description |
| --- | --- |
| (default) | The label and any icons. Slotted `<svg>` elements are sized to `calc(var(--spacing) * 4)`. |

### CSS parts

| Part | Description |
| --- | --- |
| `button` | The inner native `<button>`. |

### CSS states and custom properties

| Name | Description |
| --- | --- |
| `--ui-radius-start` | Overrides the start corner radii. `ui-button-group` sets it to `0` to join buttons. |
| `--ui-radius-end` | Overrides the end corner radii. |
| `:state(attr-variant-is-*)`, `:state(attr-size-is-*)` | Set for the current variant and size, for example `ui-button:state(attr-variant-is-outline)`. |

### Forms

`ui-button` is form-associated through `ElementInternals`, so it finds its form even across shadow roots.
`type="submit"` calls `requestSubmit()` on the form, which runs constraint validation and fires `submit`.
`type="reset"` calls `reset()`. The button itself adds no name or value to the submitted data, and the `submit`
event's `submitter` is `null`.

### Accessibility

The host delegates focus to the inner native `<button>`, so Enter and Space
activate it as usual. `aria-label` is passed to the inner button. A disabled button is removed from the tab order.


---

# `start`

Source: http://realm.js.org/reference/javascript/start/

Starts REALM in the current document. `realm.js` calls it for you.

```ts
start(): void
```

```html
<script type="module">
  import { start } from "https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/index.js";

  start();
</script>
```

## What it does

1. Adopts a page stylesheet: `custom-element, import-element { display: none !important }` and `is-visible, is-hidden, repeat-list { display: contents }`.
2. Registers `<import-element>`, unless something already defined that name.
3. Defines every `<custom-element>` in the document and removes it from the page.
4. Watches the document with a `MutationObserver`: `<custom-element>` elements added later are defined too, and custom tags are noticed for [lazy imports](/reference/elements/import-element/#example-lazy-loading-and-the-load-event).

Inline definitions are resolved against `document.baseURI`.

## Notes

- Safe to call more than once. Later calls do nothing.
- Takes no arguments and returns nothing. Definitions are created asynchronously, and elements upgrade as their definitions arrive.

## Related

- [Installation: from a CDN](/docs/installation/#add-realm-from-the-cdn)


---

# Button Group

Source: http://realm.js.org/components/button-group/

`ui-button-group` lays its children out in a row or column and removes the inner corner radii, so neighbouring
`ui-button` (or `ui-toggle`) elements read as one control. The host has the `group` role. It only handles layout
and does not track a value. For a group of pressable buttons with a selected value, use
[Toggle Group](/components/toggle-group).

```html live
<ui-button-group aria-label="Text alignment">
  <ui-button variant="outline">Left</ui-button>
  <ui-button variant="outline">Center</ui-button>
  <ui-button variant="outline">Right</ui-button>
</ui-button-group>
```

## Examples

### Icon buttons

Group icon buttons for toolbars. Each icon button needs its own `aria-label`.

```html live
<ui-button-group aria-label="History">
  <ui-button variant="outline" size="icon" aria-label="Undo">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M9 14 4 9l5-5" /><path d="M4 9h11a5 5 0 0 1 0 10h-4" /></svg>
  </ui-button>
  <ui-button variant="outline" size="icon" aria-label="Redo">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m15 14 5-5-5-5" /><path d="M20 9H9a5 5 0 0 0 0 10h4" /></svg>
  </ui-button>
</ui-button-group>
```

### Split button

A primary action next to a second button that opens more options.

```html live
<ui-button-group aria-label="Merge">
  <ui-button>Merge pull request</ui-button>
  <ui-button size="icon" aria-label="More merge options" popovertarget="button-group-menu">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
  </ui-button>
</ui-button-group>
<div id="button-group-menu" popover>Squash and merge, or rebase and merge.</div>
```

### Separator

Buttons with a filled background have no border between them. Put a `ui-button-group-separator` between them to
draw one.

```html live
<ui-button-group aria-label="Copy and share">
  <ui-button variant="secondary" size="sm">Copy</ui-button>
  <ui-button-group-separator></ui-button-group-separator>
  <ui-button variant="secondary" size="sm">Paste</ui-button>
</ui-button-group>
```

### Text

`ui-button-group-text` adds a bordered label to the group, joined like the buttons.

```html live
<ui-button-group aria-label="Zoom">
  <ui-button variant="outline" size="icon" aria-label="Zoom out">−</ui-button>
  <ui-button-group-text>100%</ui-button-group-text>
  <ui-button variant="outline" size="icon" aria-label="Zoom in">+</ui-button>
</ui-button-group>
```

### Vertical

`orientation="vertical"` stacks the buttons and joins the top and bottom corners. A separator in a vertical group
takes `orientation="horizontal"`.

```html live
<ui-button-group orientation="vertical" aria-label="Volume">
  <ui-button variant="secondary" size="icon" aria-label="Louder">+</ui-button>
  <ui-button-group-separator orientation="horizontal"></ui-button-group-separator>
  <ui-button variant="secondary" size="icon" aria-label="Quieter">−</ui-button>
</ui-button-group>
```

### Form actions

Grouped buttons keep their form behaviour, so a group can hold the submit and reset actions of a form.

```html live
<custom-element name="button-group-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      result.text = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`).join("\n");
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-input name="query" value="button group" aria-label="Search"></ui-input>
    <ui-button-group aria-label="Search actions">
      <ui-button type="submit">Search</ui-button>
      <ui-button type="reset" variant="outline">Clear</ui-button>
    </ui-button-group>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<button-group-form-demo></button-group-form-demo>
```

## API

### Parts

| Element | Fills | Renders |
| --- | --- | --- |
| `ui-button-group` | | A `role="group"` row or column that joins its children's corners. |
| `ui-button-group-text` | the default slot of `ui-button-group` | A bordered, muted label joined like a button. |
| `ui-button-group-separator` | the default slot of `ui-button-group` | A one-pixel `role="separator"` line between two buttons. |

### Attributes

#### ui-button-group

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal"` \| `"vertical"` | `"horizontal"` | Lays the children out in a row or a column. |

#### ui-button-group-separator

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"vertical"` \| `"horizontal"` | `"vertical"` | Direction of the line. Use `"horizontal"` in a vertical group. Sets `aria-orientation`. |

### Slots

| Slot | Description |
| --- | --- |
| (default) | The grouped buttons. Every child except the first gets `--ui-radius-start: 0` and a `-1px` start margin so borders overlap. Every child except the last gets `--ui-radius-end: 0`. |

### CSS states and custom properties

| Name | Description |
| --- | --- |
| `:state(attr-orientation-is-vertical)` | Set when `orientation="vertical"`. |

The group sets `--ui-radius-start` and `--ui-radius-end` on its children. `ui-button`, `ui-toggle` and
`ui-button-group-text` read them. Other children can use them for their own corner radii.

### Accessibility

The host has `role="group"`. Give it an `aria-label` that names what the buttons do together.


---

# `importDefinitions`

Source: http://realm.js.org/reference/javascript/import-definitions/

Loads an HTML file and defines every `<custom-element>` in it. The JavaScript form of [`<import-element>`](/reference/elements/import-element/).

```ts
importDefinitions(url: string): Promise<void>
```

```js
import { importDefinitions } from "https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/index.js";

await importDefinitions(new URL("components/chart.html", document.baseURI).href);
document.body.append(document.createElement("sales-chart"));
```

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `url` | `string` | Absolute URL of the file. Relative URLs inside the file resolve against it |

## Returns

A promise that resolves when every definition in the file is defined. It rejects with an error whose message is `Could not import URL (HTTP status)` and which carries `url` and `status` (`0` for network errors).

## Behaviour

- The file is fetched once per page. `<import-element>` tags and other calls for the same URL share the request.
- At most six imports per origin run at once.
- The file is parsed with `DOMParser` and never executed. Only `<custom-element>` elements are used.
- Unlike `<import-element>`, it does not log a warning on failure. Handle the rejection yourself.

## Related

- [Importing components: from JavaScript](/docs/importing/#from-javascript)


---

# Calendar

Source: http://realm.js.org/components/calendar/

`ui-calendar` shows one month as a grid of day buttons. Clicking a day selects it, and the selected date is the
element's `value` in `YYYY-MM-DD` form. The calendar is form-associated. Give it a `name` and the form submits the selected
date in the same format a native `<input type="date">` uses.

Dates are handled as plain calendar days in UTC, so a value never shifts across time zones. Today is the user's
local date. Month and weekday names come from `Intl.DateTimeFormat`, and weeks always start on Sunday.

```html live
<ui-calendar></ui-calendar>
```

## Examples

### Selected date

Set `value` to preselect a date. The calendar opens on that date's month.

```html live
<ui-calendar value="2026-03-14"></ui-calendar>
```

### Minimum and maximum

Days before `min` or after `max` are disabled and cannot be selected.

```html live
<ui-calendar value="2026-06-10" min="2026-06-05" max="2026-06-24"></ui-calendar>
```

### Starting month

`month` (`YYYY-MM`) sets the month shown first when there is no value to show.

```html live
<ui-calendar month="2026-12"></ui-calendar>
```

### Locale

`locale` is a BCP 47 language tag for the month title and weekday names. Without it the browser's default locale
is used.

```html live
<ui-calendar locale="fr-FR" value="2026-07-14"></ui-calendar>
<ui-calendar locale="ja-JP" value="2026-07-14"></ui-calendar>
```

### Listening for changes

The calendar fires `change` when a day is picked. Read the new date from `value`.

```html live
<custom-element name="calendar-change-demo">
  <script type="realm">
    const picked = useState({ date: "nothing yet" });

    function changed(calendar) {
      picked.date = calendar.value;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: center;
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>

  <ui-calendar month="2026-10" onchange="changed(this)"></ui-calendar>
  <p>Selected: <slot name="#picked.date"></slot></p>
</custom-element>
<calendar-change-demo></calendar-change-demo>
```

### In a form

The calendar submits its `value` under its `name`. Resetting the form returns it to the `value` attribute.

```html live
<custom-element name="calendar-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      result.text = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`).join("\n");
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      justify-items: start;
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: start;
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      box-sizing: border-box;
      width: 100%;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-calendar name="checkin" value="2026-08-03" min="2026-08-01"></ui-calendar>
    <div class="actions">
      <ui-button type="submit">Book</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<calendar-form-demo></calendar-form-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `""` | Selected date as `YYYY-MM-DD`. Empty means no selection. |
| `month` | string | | Month shown first, as `YYYY-MM`. Used when the calendar is created. Defaults to the month of `value`, or the current month. |
| `min` | string | | Earliest selectable date, `YYYY-MM-DD`. |
| `max` | string | | Latest selectable date, `YYYY-MM-DD`. |
| `locale` | string | | Locale for the month title and weekday names. Defaults to the browser locale. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `value` | string | The selected date. Setting it updates the selection and the submitted value. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `change` | none | Fired after the user picks a day. |

### CSS parts

| Part | Description |
| --- | --- |
| `header` | The row with the previous and next month buttons and the month title. |
| `grid` | The `<table>` holding the weekday headings and days. |
| `day` | Each day `<button>`. It carries `data-date`, plus `data-outside` for days of the neighbouring months, `data-today` for today, `aria-selected="true"` for the selected day and `disabled` outside `min`/`max`. |

`::part(day)` accepts pseudo-classes such as `:hover` and `:disabled` but not attribute selectors, so the
selected, today and outside colours come from the theme tokens (`--primary`, `--accent`, `--muted-foreground`).

### Forms

`ui-calendar` is form-associated. With a `name`, the form submits `value` (`YYYY-MM-DD`), or nothing when no date is
selected. `form.reset()` restores the `value` attribute, and the browser's form state restore brings back a
selected date after navigation.

### Accessibility

The days are a table with `role="grid"`, and the selected day has `aria-selected="true"`. The month title is an
`aria-live="polite"` region, so month changes are announced. Only one day is in the tab order at a time (the
selected day, or today when nothing is selected).

| Key | Action |
| --- | --- |
| Arrow Left / Arrow Right | Move focus one day back or forward. |
| Arrow Up / Arrow Down | Move focus one week back or forward. Moving past the edge of the month shows the next or previous month. |
| Enter / Space | Select the focused day. |
| Tab | Leave the grid. The previous and next month buttons come before it in tab order. |


---

# `defineComponent`

Source: http://realm.js.org/reference/javascript/define-component/

Defines a component from a `<custom-element>` element you already have. `start()` and `<import-element>` use it. Most pages never call it directly.

```ts
defineComponent(element: Element, base: string, inline: boolean): Promise<void>
```

```js
import { defineComponent } from "https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/index.js";

const doc = new DOMParser().parseFromString(html, "text/html");
for (const definition of doc.querySelectorAll("custom-element")) {
  await defineComponent(definition, sourceUrl, false);
}
```

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `element` | `Element` | A `<custom-element>` element. It is read, not inserted. Its non-script, non-style children are moved into the definition |
| `base` | `string` | URL that relative `<link href>`, `<script src>` and `import` specifiers resolve against. Also shown in duplicate-definition warnings |
| `inline` | `boolean` | `true` for definitions that were written in the page. REALM then warns if the script is not `type="realm"` |

## Returns

A promise that resolves once the element class is registered with `customElements.define` (after the script has been assembled or loaded). It resolves without defining anything when the name has no dash, is already defined by REALM, or is owned by another library. Each of these cases logs a warning, except an identical re-definition.

## Related

- [`<custom-element>`](/reference/elements/custom-element/)
- [Component anatomy: how it works without a compiler](/docs/components/#how-it-works-without-a-compiler)


---

# Checkbox

Source: http://realm.js.org/components/checkbox/

`ui-checkbox` renders a native `<input type="checkbox">` and a `<label>` in its shadow root. The element's text is
the label, and clicking the label toggles the box. It is form-associated. When checked, it submits its `value`
(or `on`) under its `name`, like a native checkbox.

```html live
<ui-checkbox>Accept terms and conditions</ui-checkbox>
```

## Examples

### Checked

```html live
<ui-checkbox checked>Email me about product updates</ui-checkbox>
```

### Indeterminate

`indeterminate` shows a dash instead of a check mark, for a "select all" box whose items are partly checked. Like
the native property, it changes only the look. The box still submits according to `checked`. Clicking the box clears
`indeterminate`, as it does on a native checkbox.

```html live
<ui-checkbox indeterminate>Select all</ui-checkbox>
```

### Disabled

```html live
<ui-checkbox disabled>Disabled</ui-checkbox>
<ui-checkbox disabled checked>Disabled and checked</ui-checkbox>
```

### Without visible text

When the checkbox has no text, name it with `aria-label`.

```html live
<ui-checkbox aria-label="Select row"></ui-checkbox>
```

### Listening for changes

`change` bubbles from the element after each toggle. Read `checked` from the element.

```html live
<custom-element name="checkbox-change-demo">
  <script type="realm">
    const settings = useState({ status: "Notifications are off." });

    function changed(checkbox) {
      settings.status = checkbox.checked ? "Notifications are on." : "Notifications are off.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>

  <ui-checkbox onchange="changed(this)">Enable notifications</ui-checkbox>
  <p role="status"><slot name="#settings.status"></slot></p>
</custom-element>
<checkbox-change-demo></checkbox-change-demo>
```

### In a form

Only checked boxes are submitted. Several checkboxes can share a `name`, and `FormData.getAll()` returns every checked
value. `required` blocks submission until the box is checked, and `form.reset()` restores the `checked` attribute.

```html live
<custom-element name="checkbox-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      const entries = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`);
      result.text = entries.join("\n") || "(nothing submitted)";
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-checkbox name="topics" value="releases" checked>Releases</ui-checkbox>
    <ui-checkbox name="topics" value="security">Security advisories</ui-checkbox>
    <ui-checkbox name="topics" value="events">Events</ui-checkbox>
    <ui-checkbox name="terms" required>I agree to the terms</ui-checkbox>
    <div class="actions">
      <ui-button type="submit">Subscribe</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<checkbox-form-demo></checkbox-form-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | boolean | `false` | Whether the box is checked. The attribute is the initial and reset state. The property follows the user. |
| `value` | string | | Value submitted when checked. Without it the form submits `on`. |
| `indeterminate` | boolean | `false` | Shows the mixed state. Visual only. Cleared when the user toggles the box. |
| `disabled` | boolean | `false` | Disables the box. Also true inside a disabled `<fieldset>`. |
| `required` | boolean | `false` | The form is invalid until the box is checked. |
| `aria-label` | string | | Accessible name when there is no visible text. Property name: `label`. |

The `name` attribute is read by the form, as on any form-associated element.

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `checked` | boolean | Current state. Updated when the user toggles the box. Setting it updates the box and the submitted value. |
| `value`, `indeterminate`, `disabled`, `required` | | Mirror the attributes above. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `change` | none | Bubbles from the element after the user toggles the box. `checked` is already updated. |
| `input` | none | The native `input` event of the inner checkbox, which is composed and reaches the page. |

### Slots

| Slot | Description |
| --- | --- |
| (default) | The label text. It is rendered inside a native `<label>` for the inner checkbox. |

### CSS parts

| Part | Description |
| --- | --- |
| `control` | The inner `<input type="checkbox">`. |
| `label` | The `<label>` around the slotted text. |

### CSS states

| State | Description |
| --- | --- |
| `:state(attr-checked)` | Set while the box is checked, for example `ui-checkbox:state(attr-checked)`. |

### Forms

`ui-checkbox` is form-associated. When checked it submits `value`, or `on` without one. When unchecked it submits
nothing. Validity is mirrored from the inner checkbox, so `required` takes part in `checkValidity()` and
`reportValidity()`. `form.reset()` restores the `checked` attribute, and a disabled `<fieldset>` disables the box.

### Accessibility

The inner native checkbox keeps its role, Space toggles it, and the host delegates focus to it. The slotted text is
its label. When there is no text, `aria-label` is passed to the inner checkbox, and a `<ui-label for>` pointing at
the element sets one too.


---

# `flush`

Source: http://realm.js.org/reference/javascript/flush/

Runs every queued observer and binding update now, instead of at the end of the microtask.

```ts
flush(): void
```

```js
import { flush } from "https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/index.js";

state.items.push(item);
flush();
// the DOM shows the new item here
```

## Behaviour

- Updates run in rounds until nothing is queued. After 100 rounds, the queue is cleared and `Update loop detected: an observer keeps changing state it depends on.` is reported.
- Calling it with nothing queued does nothing.
- Inside a component script, prefer `await tick()`, which waits a microtask and then flushes. `flush` is not one of the script helpers.
- Fetch attributes call `flush()` before building a request, so a request sees state changed earlier in the same event.

## Related

- [`tick`](/reference/script/tick/)
- [State and reactivity: updates are batched](/docs/state/#updates-are-batched)


---

# Combobox

Source: http://realm.js.org/components/combobox/

`ui-combobox` is a text input with a filterable list of choices, following the ARIA combobox pattern. The choices
are plain `<option>` elements written as children, like in a `<select>`. Typing filters them by label, and picking
one sets the element's `value`. The list is a native manual popover, so it renders in the top layer. It opens when
the input is focused or clicked, and closes on Escape, on a choice and when focus leaves the input.

It is form-associated. With a `name`, the chosen option's `value` is submitted with the form. Like a native form
control in a form field, it fills the width of its container. `width` gives it a fixed width instead.

```html live
<ui-combobox aria-label="Framework" placeholder="Select a framework…" width="60">
  <option value="realm">REALM</option>
  <option value="lit">Lit</option>
  <option value="stencil">Stencil</option>
  <option value="fast">FAST</option>
  <option value="vanilla">Vanilla custom elements</option>
</ui-combobox>
```

## Examples

### Preselected value

Set `value` to the `value` of one of the options. The input shows that option's label.

```html live
<ui-combobox aria-label="Time zone" value="europe-berlin">
  <option value="america-new-york">New York (UTC-5)</option>
  <option value="europe-london">London (UTC+0)</option>
  <option value="europe-berlin">Berlin (UTC+1)</option>
  <option value="asia-tokyo">Tokyo (UTC+9)</option>
</ui-combobox>
```

### Disabled options

A `disabled` option is shown dimmed and cannot be chosen.

```html live
<ui-combobox aria-label="Plan" placeholder="Choose a plan…">
  <option value="free">Free</option>
  <option value="pro">Pro</option>
  <option value="enterprise" disabled>Enterprise (contact sales)</option>
</ui-combobox>
```

### Option labels

The visible text comes from the option's `label` attribute, or its text when there is no `label`, as with native
options. Filtering matches the label.

```html live
<ui-combobox aria-label="Country" placeholder="Search countries…">
  <option value="DE" label="Germany">DE</option>
  <option value="FR" label="France">FR</option>
  <option value="JP" label="Japan">JP</option>
  <option value="BR" label="Brazil">BR</option>
</ui-combobox>
```

### Empty state

`ui-combobox-empty` replaces the default "No results found." text shown when nothing matches the query.

```html live
<ui-combobox aria-label="Language" width="60">
  <option value="en">English</option>
  <option value="es">Spanish</option>
  <option value="id">Indonesian</option>
  <ui-combobox-empty>No language matches that search.</ui-combobox-empty>
</ui-combobox>
```

### Width

By default the combobox fills its container. `width` sets a fixed width in spacing units, so `width="48"` is
`calc(var(--spacing) * 48)`.

```html live
<div class="demo-stack">
  <ui-combobox aria-label="Fruit" placeholder="Fills the container">
    <option value="apple">Apple</option>
  </ui-combobox>
  <ui-combobox aria-label="Fruit" placeholder="width=48" width="48">
    <option value="apple">Apple</option>
  </ui-combobox>
</div>
```

### Disabled

```html live
<ui-combobox aria-label="Framework" value="realm" disabled>
  <option value="realm">REALM</option>
</ui-combobox>
```

### Dynamic options

The combobox watches its `<option>` children, so options rendered from state with `repeat` show up in the list.

```html live
<custom-element name="combobox-dynamic-demo">
  <script type="realm">
    const catalog = useState({
      fruits: [
        { id: "apple", name: "Apple" },
        { id: "banana", name: "Banana" },
      ],
      chosen: "",
    });

    function addCherry() {
      if (catalog.fruits.some((fruit) => fruit.id === "cherry")) return;
      catalog.fruits = [...catalog.fruits, { id: "cherry", name: "Cherry" }];
    }

    function changed(combobox) {
      catalog.chosen = combobox.value;
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      flex-wrap: wrap;
      align-items: center;
      gap: calc(var(--spacing) * 3);
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>

  <ui-combobox aria-label="Fruit" placeholder="Pick a fruit…" onchange="changed(this)">
    <option repeat="#catalog.fruits" as="fruit" key="id" _value="#fruit.id" _label="#fruit.name"></option>
  </ui-combobox>
  <ui-button variant="outline" onclick="addCherry()">Add cherry</ui-button>
  <p>value: <slot name="#catalog.chosen"></slot></p>
</custom-element>
<combobox-dynamic-demo></combobox-dynamic-demo>
```

### In a form

The chosen `value` is submitted under the element's `name`. With `required`, the form is invalid until an option is
chosen, and `form.reset()` returns to the `value` attribute.

```html live
<custom-element name="combobox-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      const entries = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`);
      result.text = entries.join("\n") || "(nothing submitted)";
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-combobox name="framework" aria-label="Framework" required>
      <option value="realm">REALM</option>
      <option value="lit">Lit</option>
      <option value="stencil">Stencil</option>
    </ui-combobox>
    <div class="actions">
      <ui-button type="submit">Save</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<combobox-form-demo></combobox-form-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-combobox` | | The text input with a chevron and the popover list. Fills its container's width unless `width` is set. |
| `<option>` | (data) | One choice in the list, with a check mark when chosen. |
| `ui-combobox-empty` | `empty` | The text shown when nothing matches, in place of "No results found.". |

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `""` | The `value` of the chosen option. |
| `placeholder` | string | `"Select…"` | Placeholder of the text input. |
| `width` | number | | Fixed width in spacing units, where `n` means `calc(var(--spacing) * n)`. Without it the combobox fills its container. |
| `disabled` | boolean | `false` | Disables the input. Also true inside a disabled `<fieldset>`. |
| `required` | boolean | `false` | The form is invalid until an option is chosen. |
| `aria-label` | string | | Accessible name, passed to the inner input. Property name: `label`. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `value` | string | The chosen value. Setting it selects the matching option. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `change` | none | Fired after the user chooses an option. |

### Child elements

| Element | Attributes read | Description |
| --- | --- | --- |
| `<option>` | `value`, `label` (or text), `disabled` | One choice. Options are hidden in place and rendered in the list. Adding, removing or changing options updates the list. |
| `ui-combobox-empty` | | Rich content for the empty state. |

### CSS parts

| Part | Description |
| --- | --- |
| `field` | The bordered box around the input and chevron. |
| `input` | The inner text `<input role="combobox">`. |
| `list` | The popover `role="listbox"` element. |
| `option` | Each rendered option (`role="option"`). |
| `empty` | The paragraph shown when nothing matches. |

### Forms

`ui-combobox` is form-associated. With a `name`, it submits `value`, or an empty string when nothing is chosen. With
`required` and no value it reports `valueMissing` with the message "Please select an item." and the validation
bubble points at the input. `form.reset()` restores the `value` attribute.

### Accessibility

The inner input has `role="combobox"`, `aria-autocomplete="list"`, `aria-controls` pointing at the listbox and
`aria-expanded` while the list is open. Options have `role="option"`, with `aria-selected` on the chosen one and
`aria-disabled` on disabled ones. The highlighted option follows the arrow keys while focus stays in the input, and
the input's `aria-activedescendant` points at it while the list is open.

| Key | Action |
| --- | --- |
| Tab into the input | Opens the list. |
| Typing | Opens the list and filters the options by label. |
| Arrow Down / Arrow Up | Opens the list and moves the highlight, wrapping at the ends. |
| Enter | Chooses the highlighted option and closes the list. |
| Escape | Closes the list. |


---

# `toRaw`

Source: http://realm.js.org/reference/javascript/to-raw/

Returns the original object behind a reactive proxy. Anything else is returned unchanged.

```ts
toRaw<T>(value: T): T
```

```js
import { toRaw } from "https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/index.js";

const snapshot = structuredClone(toRaw(todo.items));
worker.postMessage(toRaw(settings));
```

## Use it for

| Case | Why |
| --- | --- |
| `structuredClone`, `postMessage`, IndexedDB | Proxies cannot be cloned |
| Identity checks against objects created outside REALM | `toRaw(proxy) === original` |
| Heavy read-only work | Reading the raw object does not subscribe |

Nested values of the raw object are raw too. Writing to the raw object does **not** notify observers.

## Related

- [`useState`](/reference/script/use-state/)


---

# Field

Source: http://realm.js.org/components/field/

`ui-field` stacks a label, a control, an optional `ui-field-description` and an error message with consistent
spacing. It is a layout element with the `group` role. The control inside keeps its own form behaviour. Its parts go
in the default slot and show in source order. `ui-field-group` stacks several fields, and `ui-field-set` groups
fields under a `ui-field-legend`.

Pair the label with the control through `ui-label for`, which also gives the control its accessible name.

```html live
<div class="demo-narrow">
  <ui-field>
    <ui-label for="field-email">Email</ui-label>
    <ui-input id="field-email" type="email" placeholder="m@example.com"></ui-input>
    <ui-field-description>We only use it to send receipts.</ui-field-description>
  </ui-field>
</div>
```

## Examples

### Error message

`error` shows a message below the field in a `role="alert"` paragraph, and `invalid` colours the label. Set
`invalid` on the control as well so its border and `aria-invalid` match.

```html live
<div class="demo-narrow">
  <ui-field invalid error="Choose a username with at least 3 characters.">
    <ui-label for="field-username">Username</ui-label>
    <ui-input id="field-username" value="ab" invalid></ui-input>
  </ui-field>
</div>
```

### Horizontal

`orientation="horizontal"` puts the label and control on one row, which suits switches and checkboxes.

```html live
<div class="demo-narrow">
  <ui-field orientation="horizontal">
    <ui-label for="field-marketing">Marketing emails</ui-label>
    <ui-switch id="field-marketing"></ui-switch>
  </ui-field>
</div>
```

### Horizontal with a description

Wrap the label and description in `ui-field-content` so they stay together in a column beside the control. Source
order decides which side the control is on.

```html live
<div class="demo-medium">
  <ui-field orientation="horizontal">
    <ui-checkbox id="field-sync"></ui-checkbox>
    <ui-field-content>
      <ui-label for="field-sync">Sync across devices</ui-label>
      <ui-field-description>Your settings follow you to every device you sign in on.</ui-field-description>
    </ui-field-content>
  </ui-field>
</div>
```

### Field group

`ui-field-group` stacks fields with a larger gap than the parts inside a field.

```html live
<div class="demo-narrow">
  <ui-field-group>
    <ui-field>
      <ui-label for="field-first-name">First name</ui-label>
      <ui-input id="field-first-name" autocomplete="given-name"></ui-input>
    </ui-field>
    <ui-field>
      <ui-label for="field-last-name">Last name</ui-label>
      <ui-input id="field-last-name" autocomplete="family-name"></ui-input>
    </ui-field>
  </ui-field-group>
</div>
```

### Field set

`ui-field-set` takes a `ui-field-legend`, an optional `ui-field-description` and the fields. The legend names the
group.

```html live
<div class="demo-medium">
  <ui-field-set>
    <ui-field-legend>Shipping address</ui-field-legend>
    <ui-field-description>Where should we send the order?</ui-field-description>
    <ui-field-group>
      <ui-field>
        <ui-label for="field-street">Street</ui-label>
        <ui-input id="field-street" autocomplete="street-address"></ui-input>
      </ui-field>
      <ui-field>
        <ui-label for="field-city">City</ui-label>
        <ui-input id="field-city" autocomplete="address-level2"></ui-input>
      </ui-field>
    </ui-field-group>
  </ui-field-set>
</div>
```

### Legend as a label

`variant="label"` on `ui-field-legend` uses label-sized text, for a set of checkboxes or radios.

```html live
<div class="demo-narrow">
  <ui-field-set>
    <ui-field-legend variant="label">Notify me about</ui-field-legend>
    <ui-field-group>
      <ui-field orientation="horizontal">
        <ui-checkbox id="field-notify-mentions" checked></ui-checkbox>
        <ui-label for="field-notify-mentions">Mentions</ui-label>
      </ui-field>
      <ui-field orientation="horizontal">
        <ui-checkbox id="field-notify-replies"></ui-checkbox>
        <ui-label for="field-notify-replies">Replies</ui-label>
      </ui-field>
    </ui-field-group>
  </ui-field-set>
</div>
```

### In a form

Fields do not change what a form submits. The controls inside do. This form validates on submit and shows the
errors through `error` and `invalid`.

```html live
<custom-element name="field-form-demo">
  <script type="realm">
    const signup = useState({
      nameError: "",
      emailError: "",
      text: "Submit the form to see its data.",
      get nameInvalid() {
        return this.nameError !== "";
      },
      get emailInvalid() {
        return this.emailError !== "";
      },
    });

    function submit(event) {
      event.preventDefault();
      const data = new FormData(event.target);
      signup.nameError = data.get("name") ? "" : "Enter your name.";
      signup.emailError = String(data.get("email")).includes("@") ? "" : "Enter a valid email address.";
      if (signup.nameError || signup.emailError) {
        signup.text = "Fix the errors above.";
        return;
      }
      signup.text = [...data].map(([name, value]) => `${name}=${value}`).join("\n");
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 96);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 6);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" novalidate>
    <ui-field-set>
      <ui-field-legend>Profile</ui-field-legend>
      <ui-field-description>This is shown on your public page.</ui-field-description>
      <ui-field _invalid="#signup.nameInvalid" _error="#signup.nameError">
        <ui-label for="field-form-name">Name</ui-label>
        <ui-input id="field-form-name" name="name" _invalid="#signup.nameInvalid"></ui-input>
      </ui-field>
      <ui-field _invalid="#signup.emailInvalid" _error="#signup.emailError">
        <ui-label for="field-form-email">Email</ui-label>
        <ui-input id="field-form-email" name="email" type="email" _invalid="#signup.emailInvalid"></ui-input>
        <ui-field-description>Used for sign-in only.</ui-field-description>
      </ui-field>
      <ui-field orientation="horizontal">
        <ui-label for="field-form-public">Public profile</ui-label>
        <ui-switch id="field-form-public" name="public" checked></ui-switch>
      </ui-field>
    </ui-field-set>
    <ui-button type="submit">Save profile</ui-button>
  </form>
  <output><slot name="#signup.text"></slot></output>
</custom-element>
<field-form-demo></field-form-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-field` | | One field: label, control, description and error, stacked (or in a row when horizontal). Role `group`. |
| `ui-label` | (default) | The label of a `ui-field`. A plain child. See [Label](/components/label/). |
| `ui-field-content` | (default) | A column that keeps a label and description together beside the control in a horizontal field. |
| `ui-field-description` | (default) | Help text in muted `var(--text-sm)`. Goes in `ui-field`, `ui-field-content` or `ui-field-set`. |
| `ui-field-group` | (default) | A column of fields with a gap of `calc(var(--spacing) * 7)`. |
| `ui-field-set` | | A group of fields under a legend. Role `group`. |
| `ui-field-legend` | `legend` | The heading of a `ui-field-set`. Assigns itself to the `legend` slot, so you do not set `slot`. |

Parts show in source order. Every part's default slot takes any content.

### ui-field attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"vertical"` \| `"horizontal"` | `"vertical"` | Stacks the parts, or puts them on one row. |
| `invalid` | boolean | `false` | Colours the label with `--destructive`. |
| `error` | string | | Error message shown below the field. Hidden when empty. |

### ui-field-legend attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"label"` | | Uses `var(--text-sm)` instead of `var(--text-base)`. |

The other parts have no attributes.

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-field` | `error` | The error paragraph (`role="alert"`). |

### CSS states

| Element | State | Description |
| --- | --- | --- |
| `ui-field` | `:state(attr-invalid)` | Set while `invalid` is present. |
| `ui-field` | `:state(attr-orientation-is-horizontal)` | Set for the horizontal layout. |

### Accessibility

`ui-field` has `role="group"`. Its `error` paragraph has `role="alert"`, so a message that appears is announced.
The field does not link its label, description or error to the control. Use `ui-label for` (or `aria-label` on the
control) for the name. `ui-field-set` has `role="group"` and takes its accessible name from its `ui-field-legend`.


---

# `untrack`

Source: http://realm.js.org/reference/javascript/untrack/

Runs a function and returns its result without subscribing the current observer to anything it reads.

```ts
untrack<T>(fn: () => T): T
```

```js
import { observe, untrack } from "https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/index.js";

observe(() => {
  const query = search.query;
  const limit = untrack(() => settings.limit);
  run(query, limit);
});
```

The observer above re-runs when `search.query` changes, not when `settings.limit` changes.

## Notes

- Writes inside `fn` still notify other observers.
- In a component script, `untrack` is available as a helper, like `observe`. Outside components, import it from the module.

## Related

- [State and reactivity: reading without subscribing](/docs/state/#reading-without-subscribing)


---

# Compiler

Source: http://realm.js.org/reference/javascript/compiler/

`compiler.js` holds REALM's build-time code. The [Vite plugin](/reference/tooling/vite-plugin/) uses it. You need it only to build your own tooling.

```js
import { compileDefinition, tokenize } from "https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/compiler.js";
```

## compileDefinition

```ts
compileDefinition(definition: Element): CompiledDefinition | undefined

interface CompiledDefinition {
  name: string;
  script: Element | undefined;
  module: string;
}
```

Turns a `<custom-element>` element into the source of a **setup module**: the script and the handler code from the markup, assembled into a function that REALM can load with `<script src>`.

| Field | Meaning |
| --- | --- |
| `name` | The definition's `name` attribute |
| `script` | The definition's `<script>` element, if any, so the caller can replace it |
| `module` | JavaScript source: hoisted `import` statements, `export const names = [...]` (the exposed top-level names) and `export default function (context) { … }` |

Returns `undefined` when there is nothing to assemble: the script already has a `src`, or there is neither script text nor any `on…` handler in the markup.

Write `module` to a file and point the definition at it with `<script src="file.js"></script>` (keep `type="realm"` for inline definitions). REALM then imports the module instead of assembling code at runtime, which lets components run under `script-src 'self'`. The Vite plugin also renames `on…` attributes inside definitions to `realm:on…` in the output HTML, so the page holds no inline handler attributes. REALM reads both forms.

Relative `import` specifiers are kept as written, so they resolve against the module file.

## tokenize

```ts
tokenize(source: string): Token[]

interface Token {
  type: "name" | "punct" | "string" | "number" | "regex" | "template";
  value: string;
  newline: boolean;
}
```

The small JavaScript tokenizer REALM uses to find top-level names and free variables. Comments are skipped. `newline` is `true` when a line break came before the token. The Vite plugin uses it to read `defineProps` for the manifest.

## Related

- [Security: Content Security Policy](/docs/security/#content-security-policy)


---

# Input

Source: http://realm.js.org/components/input/

`ui-input` wraps a native `<input>` in its shadow root and passes the usual attributes through: `type`,
`placeholder`, `pattern`, `min`, `max`, `minlength` and the rest. It is form-associated, so its `value` is
submitted under its `name`, its validity is the inner input's validity, and pressing Enter submits the form as in
a native text field.

```html live
<div class="demo-narrow">
  <ui-input aria-label="Email" type="email" placeholder="Email"></ui-input>
</div>
```

## Examples

### Types

`type` accepts the text-like and date-like native types: `text`, `email`, `password`, `number`, `search`, `tel`,
`url`, `date`, `time`, `datetime-local`, `month`, `week` and `color`. For checkboxes, radios, ranges and files use
the dedicated components or a native input.

```html live
<div class="demo-narrow demo-stack-tight">
  <ui-input type="password" aria-label="Password" placeholder="Password"></ui-input>
  <ui-input type="number" aria-label="Quantity" value="2" min="1" max="10"></ui-input>
  <ui-input type="search" aria-label="Search" placeholder="Search…"></ui-input>
  <ui-input type="date" aria-label="Start date" value="2026-10-19"></ui-input>
  <ui-input type="time" aria-label="Start time" value="09:30" step="900"></ui-input>
</div>
```

### With a label

Use `ui-label for` (or a native `<label>` around the element) to name the input. Clicking the label focuses it.

```html live
<div class="demo-narrow demo-stack-tight">
  <ui-label for="input-name">Full name</ui-label>
  <ui-input id="input-name" autocomplete="name"></ui-input>
</div>
```

### Disabled and read-only

```html live
<div class="demo-narrow demo-stack-tight">
  <ui-input aria-label="Disabled" placeholder="Disabled" disabled></ui-input>
  <ui-input aria-label="API key" value="sk-live-4f9a" readonly></ui-input>
</div>
```

### Invalid

`invalid` sets `aria-invalid` on the inner input and draws a destructive border. Use it for errors you detect
yourself, such as a taken username. Native constraint errors are reported through validity instead.

```html live
<div class="demo-narrow">
  <ui-input aria-label="Username" value="admin" invalid></ui-input>
</div>
```

### Listening for input

`input` reaches the page from the inner field as you type, and `change` fires from the element when the value is
committed. Both run after `value` is updated.

```html live
<custom-element name="input-echo-demo">
  <script type="realm">
    const echo = useState({ text: "" });

    function typed(field) {
      echo.text = field.value;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>

  <ui-input aria-label="Message" placeholder="Type something" oninput="typed(this)"></ui-input>
  <p>You typed: <slot name="#echo.text"></slot></p>
</custom-element>
<input-echo-demo></input-echo-demo>
```

### In a form

Constraint attributes (`required`, `type="email"`, `minlength`, `pattern`, `min`, `max`) block submission with the
browser's own messages. Enter inside a field submits the form. Reset returns each input to its `value` attribute.

```html live
<custom-element name="input-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      result.text = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`).join("\n");
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-input name="email" type="email" aria-label="Email" placeholder="Email" required></ui-input>
    <ui-input name="handle" aria-label="Handle" value="realm" minlength="3" pattern="[a-z0-9_]+"></ui-input>
    <ui-input name="seats" type="number" aria-label="Seats" value="5" min="1" max="50"></ui-input>
    <div class="actions">
      <ui-button type="submit">Create</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<input-form-demo></input-form-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `""` | Current value. The attribute is the initial and reset value. |
| `type` | `"text"` \| `"email"` \| `"password"` \| `"number"` \| `"search"` \| `"tel"` \| `"url"` \| `"date"` \| `"time"` \| `"datetime-local"` \| `"month"` \| `"week"` \| `"color"` | `"text"` | Native input type. |
| `placeholder` | string | | Placeholder text. |
| `autocomplete` | string | | Native autofill hint. |
| `inputmode` | string | | Virtual keyboard hint. |
| `pattern` | string | | Regular expression the value must match. |
| `min` | string | | Minimum for number and date types. |
| `max` | string | | Maximum for number and date types. |
| `step` | string | | Step for number and date types. |
| `minlength` | number | | Minimum length. |
| `maxlength` | number | | Maximum length. |
| `disabled` | boolean | `false` | Disables the input. Also true inside a disabled `<fieldset>`. |
| `readonly` | boolean | `false` | Makes the value read-only. |
| `required` | boolean | `false` | The form is invalid while the value is empty. |
| `invalid` | boolean | `false` | Sets `aria-invalid="true"` and the error style. Does not affect validity. |
| `aria-label` | string | | Accessible name, passed to the inner input. Property name: `label`. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `value` | string | Current value. Updated as the user types. Setting it updates the field and the submitted value. |

Every attribute above is also a property with the same name in camelCase (`label` for `aria-label`).

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `input` | none | The inner input's native `input` event, which is composed and reaches the page. |
| `change` | none | Dispatched from the element (bubbling) when the inner input fires `change`. |

### CSS parts

| Part | Description |
| --- | --- |
| `input` | The inner native `<input>`. |

### Forms

`ui-input` is form-associated. It submits `value` under its `name`. Validity is mirrored from the inner input, so
`required`, `type`, `pattern`, `minlength`, `maxlength`, `min`, `max` and `step` all take part in `checkValidity()`
and `reportValidity()`, and the validation bubble points at the inner field. Enter submits the form for the
text-like types. `form.reset()` restores the `value` attribute, and a disabled `<fieldset>` disables the input.

### Accessibility

The host delegates focus to the inner input. Name it with `aria-label`, `ui-label for`, or a native `<label>`
wrapped around the element. In the last two cases the label text is copied to the inner input's `aria-label`.


---

# Input Group

Source: http://realm.js.org/components/input-group/

`ui-input-group` draws one bordered box with a native `<input>` in the middle and optional addons before and after
it, such as a URL prefix, a currency symbol, a search icon, a unit or a small button. Each addon is a
`ui-input-group-addon` child. `align` puts it before (`inline-start`, the default) or after (`inline-end`) the input,
whatever its position in the source. The whole box shows the focus ring when the input is focused, and it fills the
width of its container.

It is form-associated. Only the text you type is submitted, not the addon text.

```html live
<div class="demo-narrow">
  <ui-input-group aria-label="Website" placeholder="example.com">
    <ui-input-group-addon>https://</ui-input-group-addon>
  </ui-input-group>
</div>
```

## Examples

### Icon addon

An `<svg>` in an addon is sized to `calc(var(--spacing) * 4)`.

```html live
<div class="demo-narrow">
  <ui-input-group type="search" aria-label="Search" placeholder="Search documentation…">
    <ui-input-group-addon>
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><circle cx="11" cy="11" r="7" /><path d="m20 20-3.5-3.5" /></svg>
    </ui-input-group-addon>
  </ui-input-group>
</div>
```

### Start and end addons

```html live
<div class="demo-narrow">
  <ui-input-group type="number" aria-label="Price" value="49">
    <ui-input-group-addon>$</ui-input-group-addon>
    <ui-input-group-addon align="inline-end">USD</ui-input-group-addon>
  </ui-input-group>
</div>
```

### Button addon

Put a small ghost button in an `inline-end` addon, for example to copy the value. Use `size="icon-xs"` for an
icon-only button and give it an `aria-label`.

```html live
<custom-element name="input-group-copy-demo">
  <script type="realm">
    const clip = useState({ label: "Copy" });

    async function copy() {
      await navigator.clipboard?.writeText(refs.link.value).catch(() => {});
      clip.label = "Copied";
    }
  </script>

  <style type="realm">
    :host {
      display: block;
      width: 100%;
      max-width: calc(var(--spacing) * 96);
    }
  </style>

  <ui-input-group ref="link" aria-label="Invite link" value="https://realm.dev/invite/8f2k">
    <ui-input-group-addon align="inline-end">
      <ui-button size="xs" variant="ghost" onclick="copy()"><slot name="#clip.label"></slot></ui-button>
    </ui-input-group-addon>
  </ui-input-group>
</custom-element>
<input-group-copy-demo></input-group-copy-demo>
```

### Disabled

```html live
<div class="demo-narrow">
  <ui-input-group aria-label="Username" value="ada" disabled>
    <ui-input-group-addon>@</ui-input-group-addon>
  </ui-input-group>
</div>
```

### In a form

The input's value is submitted under the element's `name`, but the addons are not. `required` takes part in validation,
Enter submits the form, and reset restores the `value` attribute.

```html live
<custom-element name="input-group-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      result.text = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`).join("\n");
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-input-group name="subdomain" aria-label="Subdomain" value="acme" required>
      <ui-input-group-addon>https://</ui-input-group-addon>
      <ui-input-group-addon align="inline-end">.realm.dev</ui-input-group-addon>
    </ui-input-group>
    <ui-input-group name="budget" type="number" aria-label="Budget" value="1200">
      <ui-input-group-addon>$</ui-input-group-addon>
    </ui-input-group>
    <div class="actions">
      <ui-button type="submit">Save</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<input-group-form-demo></input-group-form-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-input-group` | (root) | The bordered box with the native `<input>`. |
| `ui-input-group-addon` | (default) | Text, icons or buttons before or after the input, in muted colour. |

The default slot of each part takes any content.

### Attributes

#### ui-input-group

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `""` | Current value. The attribute is the initial and reset value. |
| `type` | `"text"` \| `"email"` \| `"password"` \| `"number"` \| `"search"` \| `"tel"` \| `"url"` | `"text"` | Native input type. |
| `placeholder` | string | | Placeholder text. |
| `disabled` | boolean | `false` | Disables the input. Also true inside a disabled `<fieldset>`. |
| `required` | boolean | `false` | The form is invalid while the value is empty. |
| `name` | string | | Form field name the value is submitted under. |
| `aria-label` | string | | Accessible name, passed to the inner input. Property name: `label`. |

#### ui-input-group-addon

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"inline-start"` \| `"inline-end"` | `"inline-start"` | Places the addon before or after the input. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `value` | string | Current value. Updated as the user types. Setting it updates the field. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `input` | none | The inner input's native `input` event (composed). |
| `change` | none | Dispatched from the element (bubbling) when the inner input fires `change`. |

### CSS parts

| Part | Description |
| --- | --- |
| `input` | The inner native `<input>`. |

### Forms

`ui-input-group` is form-associated. It submits the input's `value` under its `name`. Addon content is never
submitted. Validity comes from the inner input (`required` and `type`), Enter submits the form, `form.reset()`
restores the `value` attribute, and a disabled `<fieldset>` disables the input.

### Accessibility

The host delegates focus to the inner input. Addons are not part of the input's accessible name, so name the field
with `aria-label`, `ui-label for` or a wrapping `<label>`, and mark decorative icons `aria-hidden="true"`.


---

# Input OTP

Source: http://realm.js.org/components/input-otp/

`ui-input-otp` shows one native `<input>` per character of a verification code. Typing moves to the next box,
Backspace moves back, and pasting a whole code fills every box at once. Characters that do not match `pattern` are
ignored. The boxes use `autocomplete="one-time-code"`, so browsers can offer a code received by SMS.

It is form-associated. The code is the element's `value` and is submitted under its `name`.

```html live
<ui-input-otp></ui-input-otp>
```

## Examples

### Length and separator

`length` sets the number of boxes (1 to 12). `separator` adds a gap every that many boxes, for codes read in groups.

```html live
<ui-input-otp length="6" separator="3"></ui-input-otp>
<ui-input-otp length="4"></ui-input-otp>
```

### Pattern

`pattern` is a regular expression for a single character. The default accepts digits. This one accepts letters and
digits, for a recovery code.

```html live
<ui-input-otp length="8" separator="4" pattern="[A-Za-z0-9]"></ui-input-otp>
```

### Disabled

```html live
<ui-input-otp value="1234" length="4" disabled></ui-input-otp>
```

### Complete event

`complete` fires once every box is filled, with the code in `event.detail.value`. `change` fires after every edit.

```html live
<custom-element name="input-otp-verify-demo">
  <script type="realm">
    const verify = useState({ status: "Enter the code. Try 424242." });

    function complete(event) {
      verify.status = event.detail.value === "424242" ? "Code verified." : "That code is not valid.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: center;
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>

  <ui-input-otp length="6" separator="3" oncomplete="complete(event)"></ui-input-otp>
  <p role="status"><slot name="#verify.status"></slot></p>
</custom-element>
<input-otp-verify-demo></input-otp-verify-demo>
```

### In a form

The whole code is submitted as one value, even while it is incomplete. Reset
restores the `value` attribute.

```html live
<custom-element name="input-otp-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      result.text = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`).join("\n");
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: start;
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-input-otp name="code" length="6" separator="3"></ui-input-otp>
    <div class="actions">
      <ui-button type="submit">Verify</ui-button>
      <ui-button type="reset" variant="outline">Clear</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<input-otp-form-demo></input-otp-form-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `""` | The code entered so far. The attribute is the initial and reset value. |
| `length` | number | `6` | Number of boxes. An integer from 1 to 12. |
| `pattern` | string | `"[0-9]"` | Regular expression that a single character must match. |
| `separator` | number | `0` | Adds a gap before every box whose index is a multiple of this number. `0` means no gaps. |
| `disabled` | boolean | `false` | Disables every box. Also true inside a disabled `<fieldset>`. |
| `required` | boolean | `false` | The form is invalid until all boxes are filled. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `value` | string | The current code. Setting it fills the boxes. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `change` | none | Fired after each typed, pasted or deleted character. |
| `complete` | `{ value: string }` | Fired when the code reaches `length` characters. |

`complete` is a custom event name. Handle it with `oncomplete` inside a component's markup, as in the example above,
or with `addEventListener("complete", …)`.

### CSS parts

| Part | Description |
| --- | --- |
| `group` | The row of boxes (`role="group"`). |
| `slot` | Each character box. Boxes that start a new group carry `data-gap`. |

### Forms

`ui-input-otp` is form-associated and submits `value` under its `name`, even when it is incomplete. With `required`
it reports `valueMissing` with the message "Enter the full code." until all boxes are filled. The validation bubble
points at the first empty box, which takes focus. `form.reset()` restores the `value` attribute.

### Accessibility

Each box is a native text input labelled "Character N of M" and uses `inputmode="numeric"`, so phones show a number
pad. The boxes are wrapped in an element with `role="group"`.

| Key | Action |
| --- | --- |
| Character | Fills the box and moves to the next one. |
| Backspace | Clears the box, or the previous box when this one is empty, and focuses it. |
| Arrow Left / Arrow Right | Moves to the previous or next box. |
| Paste | Fills the boxes from the focused one onward with the matching characters. |


---

# Label

Source: http://realm.js.org/components/label/

`ui-label` is a styled caption for a form control. A native `<label for>` cannot reach a control inside another
element's shadow root, so `ui-label` does the work itself. With `for` set to the id of a control, it copies its text
to the control's `aria-label` (unless the control already has one), focuses the control when the label text is
clicked, and toggles it when it is a checkbox, radio or switch.

It works with native controls and with `ui-*` controls such as `ui-input`, `ui-checkbox` and `ui-switch`.

```html live
<div class="demo-narrow demo-stack-tight">
  <ui-label for="label-email">Email</ui-label>
  <ui-input id="label-email" type="email" placeholder="m@example.com"></ui-input>
</div>
```

## Examples

### With a checkbox or switch

Clicking the label text toggles the control, like a native label.

```html live
<div class="demo-stack">
  <div class="demo-row-tight">
    <ui-checkbox id="label-terms"></ui-checkbox>
    <ui-label for="label-terms">Accept terms and conditions</ui-label>
  </div>
  <div class="demo-row-tight">
    <ui-switch id="label-airplane"></ui-switch>
    <ui-label for="label-airplane">Airplane mode</ui-label>
  </div>
</div>
```

### With a native control

```html live
<div class="demo-stack-tight">
  <ui-label for="label-native">Notes</ui-label>
  <textarea id="label-native" rows="2"></textarea>
</div>
```

### In a field

Inside a `ui-field`, the label is a plain child placed before the control.

```html live
<div class="demo-narrow">
  <ui-field>
    <ui-label for="label-company">Company</ui-label>
    <ui-input id="label-company" autocomplete="organization"></ui-input>
  </ui-field>
</div>
```

### In a form

The label is not submitted. It names the controls whose values are, and clicking it works inside a form the same
way.

```html live
<custom-element name="label-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      const entries = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`);
      result.text = entries.join("\n") || "(nothing submitted)";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: start;
    }
    .row {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 2);
    }
    ui-input {
      width: 100%;
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)">
    <ui-label for="label-form-city">City</ui-label>
    <ui-input id="label-form-city" name="city" value="Lisbon"></ui-input>
    <div class="row">
      <ui-checkbox id="label-form-news" name="newsletter" value="yes"></ui-checkbox>
      <ui-label for="label-form-news">Send me the newsletter</ui-label>
    </div>
    <ui-button type="submit">Save</ui-button>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<label-form-demo></label-form-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `for` | string | | Id of the control to label, looked up in the label's own document or shadow root. |

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-label` | (default) | The label text, and optionally an icon, in a `<span>` that handles the click. Inside `ui-field` it is a plain child. |

The default slot takes any content.

### CSS parts

| Part | Description |
| --- | --- |
| `label` | The `<span>` around the slotted text. It handles the click. |

### CSS states

| State | Description |
| --- | --- |
| `:state(attr-for)` | Set while `for` is present. The label then shows a pointer cursor. |

### Accessibility

`ui-label` is not a native `<label>`, so the browser does not link it to the control. Instead, when the label is
connected it sets the target's `aria-label` to the label text, unless the target already has an `aria-label`. The
text is copied once. Changing the label text later does not update it.

Only the label text responds to clicks. The target must exist when the label is connected and be in the same document
or shadow root.


---

# Vite plugin

Source: http://realm.js.org/reference/tooling/vite-plugin/

`@realmorg/vite-plugin` is optional. REALM needs no build step. Use the plugin when a site built with Vite must run under a strict Content Security Policy, or when you want a `custom-elements.json` manifest for editors.

Add `@realmorg/vite-plugin` to the project's dev dependencies, then:

```js
// vite.config.js
import realm from "@realmorg/vite-plugin";

export default {
  plugins: [realm()],
};
```

## Options

```ts
realm(options?: RealmPluginOptions): Plugin

interface RealmPluginOptions {
  manifest?: string | false;
}
```

| Option | Type | Default | Meaning |
| --- | --- | --- | --- |
| `manifest` | `string` or `false` | `"custom-elements.json"` | File name of the manifest written to the build output, or `false` to skip it |

## What it does

| When | Effect |
| --- | --- |
| `vite build` (after the bundle is written) | Every `.html` file in the output directory (except under `node_modules`) is pre-assembled |
| `vite` dev server | HTML files requested by `fetch` (for example by `<import-element>`) are served as is, not transformed into Vite pages |

### Pre-assembly

For each `<custom-element>` in an output HTML file that has a script or `on…` handlers:

1. Its script and handler code are compiled with [`compileDefinition`](/reference/javascript/compiler/) into a module written next to the file, named `<file>.<tag-name>.js`.
2. The inline `<script>` is replaced with `<script src="./<file>.<tag-name>.js"></script>` (the `type` is kept unless it was `module`). A definition with handlers but no script gets `<script type="realm" src="…">`.
3. `on…` attributes inside definitions are renamed to `realm:on…`.

REALM then imports these modules instead of assembling code at runtime, so a policy of `script-src 'self'` (plus your CDN, if you load REALM from one) is enough. Inline `on…` attributes on plain page elements are still inline handlers and a strict policy blocks them as usual.

### Manifest

The manifest follows the [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) schema 2.1.0. For each definition it lists:

| Field | Source |
| --- | --- |
| `attributes` | Keys of the `defineProps({ … })` object, with type (`string`, `number`, `boolean`, `Date`, `array`, `object`, or the enum values joined with `\|`), attribute name (`.attribute()` or kebab-case) and `.default()` text |
| `events` | `dispatch("name"`, `new CustomEvent("name"` and `new Event("name"` in the script |
| `slots` | Named and default `<slot>` elements, except value slots |
| `cssParts` | `part` attributes in the markup |
| `cssStates` | `:state(…)` names in the definition's `<style>` |

## Outside Vite

The package also exports the functions the plugin uses:

| Export | Signature | Meaning |
| --- | --- | --- |
| `precompile` | `precompile(dir: string): PrecompileResult` | Pre-assemble every HTML file under `dir` |
| `precompileFile` | `precompileFile(path: string, root?: string): PrecompileResult` | Pre-assemble one file |
| `describe` | `describe(definition: Element, path: string)` | The manifest declaration for one definition |
| `createManifest` | `createManifest(declarations)` | The full manifest object |

`PrecompileResult` is `{ modules: string[]; definitions: Declaration[] }`: the module files written and the manifest declarations found.

## Related

- [Security: Content Security Policy](/docs/security/#content-security-policy)
- [Compiler](/reference/javascript/compiler/)


---

# Radio Group

Source: http://realm.js.org/components/radio-group/

`ui-radio-group` turns its `<option>` children into native radio buttons with labels, laid out in a column or a row.
Choosing a radio sets the group's `value`. The host has the `radiogroup` role and is form-associated. The chosen
option's `value` is submitted under the group's `name`.

Because the radios are native inputs that share a name inside the group's shadow root, the arrow keys move between
them as usual.

```html live
<ui-radio-group aria-label="Plan" value="pro">
  <option value="free">Free</option>
  <option value="pro">Pro</option>
  <option value="team">Team</option>
</ui-radio-group>
```

## Examples

### Horizontal

```html live
<ui-radio-group aria-label="Size" orientation="horizontal" value="m">
  <option value="s">Small</option>
  <option value="m">Medium</option>
  <option value="l">Large</option>
</ui-radio-group>
```

### Disabled options

`disabled` on an option disables that radio. `disabled` on the group disables all of them.

```html live
<ui-radio-group aria-label="Shipping" value="standard">
  <option value="standard">Standard (5 days)</option>
  <option value="express">Express (2 days)</option>
  <option value="overnight" disabled>Overnight (unavailable)</option>
</ui-radio-group>
<ui-radio-group aria-label="Locked plan" value="free" disabled>
  <option value="free">Free</option>
  <option value="pro">Pro</option>
</ui-radio-group>
```

### Option labels

The radio label is the option's `label` attribute, or its text when there is no `label`.

```html live
<ui-radio-group aria-label="Theme" value="system">
  <option value="light" label="Light theme">light</option>
  <option value="dark" label="Dark theme">dark</option>
  <option value="system" label="Follow the system">system</option>
</ui-radio-group>
```

### Listening for changes

```html live
<custom-element name="radio-group-change-demo">
  <script type="realm">
    const density = useState({ value: "comfortable" });

    function changed(group) {
      density.value = group.value;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>

  <ui-radio-group aria-label="Density" value="comfortable" onchange="changed(this)">
    <option value="compact">Compact</option>
    <option value="comfortable">Comfortable</option>
    <option value="spacious">Spacious</option>
  </ui-radio-group>
  <p>Density: <slot name="#density.value"></slot></p>
</custom-element>
<radio-group-change-demo></radio-group-change-demo>
```

### In a form

The chosen `value` is submitted under the group's `name`. Nothing is submitted while no option is chosen. Reset
returns the group to its `value` attribute.

```html live
<custom-element name="radio-group-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      const entries = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`);
      result.text = entries.join("\n") || "(nothing submitted)";
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 4);
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-radio-group name="billing" aria-label="Billing period" value="monthly">
      <option value="monthly">Monthly</option>
      <option value="yearly">Yearly (2 months free)</option>
    </ui-radio-group>
    <ui-radio-group name="payment" aria-label="Payment method" orientation="horizontal">
      <option value="card">Card</option>
      <option value="invoice">Invoice</option>
    </ui-radio-group>
    <div class="actions">
      <ui-button type="submit">Continue</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<radio-group-form-demo></radio-group-form-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | | The `value` of the chosen option. |
| `orientation` | `"vertical"` \| `"horizontal"` | `"vertical"` | Lays the radios out in a column or a row. |
| `disabled` | boolean | `false` | Disables every radio. Also true inside a disabled `<fieldset>`. |
| `required` | boolean | `false` | The form is invalid until an option is chosen. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `value` | string | The chosen value. Setting it checks the matching radio. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `change` | none | Fired from the group after the user chooses a radio. |

### Child elements

| Element | Attributes read | Description |
| --- | --- | --- |
| `<option>` | `value`, `label` (or text), `disabled` | One radio. Options stay hidden in place. Adding or removing options updates the radios. |

### CSS parts

| Part | Description |
| --- | --- |
| `item` | The `<label>` around each radio and its text. |
| `control` | Each native `<input type="radio">`. |

### CSS states

| State | Description |
| --- | --- |
| `:state(attr-orientation-is-horizontal)` | Set for the horizontal layout. |

### Forms

`ui-radio-group` is form-associated. It submits `value` under its `name`, or nothing while no option is chosen. With
`required` and no value it reports `valueMissing` with the message "Please select an option.", and the validation
bubble points at the first enabled radio, which takes focus. `form.reset()` restores the `value` attribute.

### Accessibility

The host has `role="radiogroup"`. Name it with `aria-label` or `aria-labelledby`. Each radio is a native input
inside its own `<label>`, so the option text is its name and clicking the text checks it. Tab moves into the group
on the checked radio, and the arrow keys move and check the next or previous radio.


---

# Select

Source: http://realm.js.org/components/select/

`ui-select` renders a native `<select>` and copies its `<option>` children into it, so you get the platform's own
picker, keyboard handling and mobile UI with the theme's styling. It is form-associated. The chosen option's
`value` is submitted under the element's `name`.

Without a `placeholder`, the select behaves like a native one. The option marked `selected`, or else the first
option, is chosen from the start. It fills the width of its container. `width` gives it a fixed width instead.

```html live
<ui-select aria-label="Fruit" width="48">
  <option value="apple">Apple</option>
  <option value="banana">Banana</option>
  <option value="blueberry">Blueberry</option>
  <option value="grapes">Grapes</option>
</ui-select>
```

## Examples

### Placeholder

`placeholder` adds an empty first entry that cannot be picked again once an option is chosen. Combine it with
`required` to make the user choose.

```html live
<ui-select aria-label="Time zone" placeholder="Select a time zone" width="60">
  <option value="utc">UTC</option>
  <option value="cet">Central European Time</option>
  <option value="jst">Japan Standard Time</option>
</ui-select>
```

### Selected option

Set `value` on the element, or `selected` on an option.

```html live
<div class="demo-row">
  <ui-select aria-label="Role" value="editor" width="40">
    <option value="viewer">Viewer</option>
    <option value="editor">Editor</option>
    <option value="admin">Admin</option>
  </ui-select>
  <ui-select aria-label="Status" width="40">
    <option value="todo">To do</option>
    <option value="doing" selected>In progress</option>
    <option value="done">Done</option>
  </ui-select>
</div>
```

### Small

```html live
<ui-select aria-label="Rows per page" size="sm" value="25" width="20">
  <option value="10">10</option>
  <option value="25">25</option>
  <option value="50">50</option>
</ui-select>
```

### Disabled

```html live
<div class="demo-row">
  <ui-select aria-label="Region" disabled width="40">
    <option value="eu">Europe</option>
  </ui-select>
  <ui-select aria-label="Plan" width="40">
    <option value="free">Free</option>
    <option value="pro">Pro</option>
    <option value="enterprise" disabled>Enterprise</option>
  </ui-select>
</div>
```

### Width

By default the select fills its container, like the inputs it sits next to in a form. `width` sets a fixed width in
spacing units, so `width="40"` is `calc(var(--spacing) * 40)`.

```html live
<div class="demo-stack">
  <ui-select aria-label="Fills the container">
    <option value="full">Fills the container</option>
  </ui-select>
  <ui-select aria-label="Fixed width" width="40">
    <option value="fixed">width="40"</option>
  </ui-select>
</div>
```

### Options from state

The select watches its `<option>` children, so options rendered with `repeat` stay in sync.

```html live
<custom-element name="select-state-demo">
  <script type="realm">
    const picker = useState({
      languages: [
        { code: "en", name: "English" },
        { code: "de", name: "Deutsch" },
        { code: "id", name: "Bahasa Indonesia" },
      ],
      chosen: "en",
    });

    function changed(select) {
      picker.chosen = select.value;
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 3);
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>

  <ui-select aria-label="Language" value="en" onchange="changed(this)">
    <option repeat="#picker.languages" as="language" key="code" _value="#language.code"><slot name="#language.name"></slot></option>
  </ui-select>
  <p>value: <slot name="#picker.chosen"></slot></p>
</custom-element>
<select-state-demo></select-state-demo>
```

### In a form

The chosen value is submitted under `name`. `required` with a placeholder blocks submission until an option is
chosen, and reset returns to the `value` attribute (or the placeholder).

```html live
<custom-element name="select-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      result.text = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`).join("\n");
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-select name="country" aria-label="Country" placeholder="Choose a country" required>
      <option value="BR">Brazil</option>
      <option value="DE">Germany</option>
      <option value="JP">Japan</option>
    </ui-select>
    <ui-select name="currency" aria-label="Currency" value="EUR">
      <option value="USD">US dollar</option>
      <option value="EUR">Euro</option>
      <option value="JPY">Yen</option>
    </ui-select>
    <div class="actions">
      <ui-button type="submit">Save</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<select-form-demo></select-form-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-select` | | A native `<select>` styled like an input, with a chevron. Fills its container's width unless `width` is set. |
| `<option>` | (data) | One choice, copied into the native select. |

The select keeps the native `<option>` children rather than separate item parts, so the platform picker, keyboard
handling and mobile UI keep working.

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `""` | The `value` of the chosen option. |
| `placeholder` | string | | Text of an empty, unselectable first entry. Without it, the first or `selected` option is chosen automatically. |
| `size` | `"default"` \| `"sm"` | `"default"` | Height of the select. |
| `width` | number | | Fixed width in spacing units, where `n` means `calc(var(--spacing) * n)`. Without it the select fills its container. |
| `disabled` | boolean | `false` | Disables the select. Also true inside a disabled `<fieldset>`. |
| `required` | boolean | `false` | The form is invalid while the placeholder is shown. |
| `aria-label` | string | | Accessible name, passed to the inner select. Property name: `label`. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `value` | string | The chosen value. Setting it selects the matching option. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `change` | none | Dispatched from the element (bubbling) after the user picks an option. |
| `input` | none | The inner select's native `input` event (composed). |

### Child elements

| Element | Attributes read | Description |
| --- | --- | --- |
| `<option>` | `value`, `label` (or text), `disabled`, `selected` | One choice. Options are copied into the inner select and kept in sync. `selected` only picks the initial option when there is no `placeholder` and no `value`. `<optgroup>` is not supported. |

### CSS parts

| Part | Description |
| --- | --- |
| `control` | The inner native `<select>`. |

### CSS states

| State | Description |
| --- | --- |
| `:state(attr-size-is-sm)` | Set for the small size. |

### Forms

`ui-select` is form-associated. It submits `value` under its `name` (an empty string while the placeholder is
shown). Validity is mirrored from the inner select, so `required` with a placeholder reports `valueMissing` and the
validation bubble points at the select. `form.reset()` restores the `value` attribute. Without one, the select goes
back to the placeholder, or to the first or `selected` option.

### Accessibility

The host delegates focus to the inner native `<select>`, which keeps the platform's keyboard support and picker.
Name it with `aria-label`, `ui-label for` or a wrapping `<label>`.


---

# Slider

Source: http://realm.js.org/components/slider/

`ui-slider` wraps a native `<input type="range">` and fills the track up to the thumb. Its `value` is a number, kept
in sync while the thumb moves. It is form-associated, so the value is submitted under its `name`, and it keeps the
native range input's keyboard support.

```html live
<div class="demo-narrow">
  <ui-slider aria-label="Volume" value="50"></ui-slider>
</div>
```

## Examples

### Range and step

`min`, `max` and `step` work as on the native input.

```html live
<div class="demo-narrow demo-stack">
  <ui-slider aria-label="Opacity" value="0.6" min="0" max="1" step="0.1"></ui-slider>
  <ui-slider aria-label="Temperature" value="21" min="16" max="28" step="0.5"></ui-slider>
</div>
```

### Showing the value

The slider does not print its value. Listen for `input` to show it while dragging.

```html live
<custom-element name="slider-value-demo">
  <script type="realm">
    const brightness = useState({ value: 70 });

    function moved(slider) {
      brightness.value = slider.value;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      width: 100%;
      max-width: calc(var(--spacing) * 72);
    }
    .row {
      display: flex;
      justify-content: space-between;
      font-size: var(--text-sm);
    }
    .value {
      color: var(--muted-foreground);
      font-variant-numeric: tabular-nums;
    }
  </style>

  <div class="row">
    <ui-label for="slider-brightness">Brightness</ui-label>
    <span class="value"><slot name="#brightness.value"></slot>%</span>
  </div>
  <ui-slider id="slider-brightness" value="70" oninput="moved(this)"></ui-slider>
</custom-element>
<slider-value-demo></slider-value-demo>
```

### Custom fill colour

The filled part of the track uses `--primary`. Override the token on an ancestor, for example with a class, to change it.

```html live
<style>
  .slider-risk {
    --primary: var(--destructive);
  }
</style>
<div class="demo-narrow slider-risk">
  <ui-slider aria-label="Risk" value="80"></ui-slider>
</div>
```

### Disabled

```html live
<div class="demo-narrow">
  <ui-slider aria-label="Locked" value="30" disabled></ui-slider>
</div>
```

### In a form

The value is submitted as a number string under `name`. Reset returns to the `value` attribute.

```html live
<custom-element name="slider-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      result.text = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`).join("\n");
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 4);
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-slider name="budget" aria-label="Budget" value="400" min="0" max="1000" step="50"></ui-slider>
    <ui-slider name="quality" aria-label="Quality" value="3" min="1" max="5"></ui-slider>
    <div class="actions">
      <ui-button type="submit">Apply</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<slider-form-demo></slider-form-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | number | `0` | Current value. The attribute is the initial and reset value. |
| `min` | number | `0` | Lowest value. |
| `max` | number | `100` | Highest value. |
| `step` | number | `1` | Granularity of the value. |
| `disabled` | boolean | `false` | Disables the slider. Also true inside a disabled `<fieldset>`. |
| `aria-label` | string | | Accessible name, passed to the inner input. Property name: `label`. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `value` | number | Current value as a number. Updated while the thumb moves. Setting it moves the thumb. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `input` | none | The inner range input's native `input` event (composed), fired while dragging. |
| `change` | none | Dispatched from the element (bubbling) when the user releases the thumb or commits a key press. |

### CSS parts

| Part | Description |
| --- | --- |
| `control` | The inner native `<input type="range">`. |

### CSS custom properties

| Property | Description |
| --- | --- |
| `--state-range-percent` | Set on the host to the filled share of the track, for example `40%`. Read-only. Use it to draw a matching tooltip or label. |

### Forms

`ui-slider` is form-associated and submits `value` under its `name`. `form.reset()` restores the `value` attribute,
and a disabled `<fieldset>` disables it.

### Accessibility

The host delegates focus to the inner native range input, which has the `slider` role and native keyboard support.
The arrow keys change the value by `step`, Page Up and Page Down by larger amounts, and Home and End jump to `min`
and `max`.


---

# Switch

Source: http://realm.js.org/components/switch/

`ui-switch` is a native `<input type="checkbox" role="switch">` drawn as a sliding toggle, with the element's text
as its label. Use it for a setting that takes effect right away. Use [Checkbox](/components/checkbox) for choices
that are confirmed later with a submit button.

It is form-associated. When on, it submits its `value` (or `on`) under its `name`, like a checkbox.

```html live
<ui-switch>Airplane mode</ui-switch>
```

## Examples

### Checked

```html live
<ui-switch checked>Wi-Fi</ui-switch>
```

### Small

```html live
<ui-switch size="sm" checked>Compact mode</ui-switch>
```

### Disabled

```html live
<ui-switch disabled>Bluetooth</ui-switch>
<ui-switch disabled checked>Location</ui-switch>
```

### Without visible text

```html live
<ui-switch aria-label="Dark mode"></ui-switch>
```

### Listening for changes

```html live
<custom-element name="switch-change-demo">
  <script type="realm">
    const sync = useState({ status: "Sync is paused." });

    function changed(control) {
      sync.status = control.checked ? "Sync is running." : "Sync is paused.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>

  <ui-switch onchange="changed(this)">Sync files</ui-switch>
  <p role="status"><slot name="#sync.status"></slot></p>
</custom-element>
<switch-change-demo></switch-change-demo>
```

### In a form

Only switches that are on are submitted. Reset restores the `checked` attribute.

```html live
<custom-element name="switch-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      const entries = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`);
      result.text = entries.join("\n") || "(nothing submitted)";
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: start;
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-switch name="email" checked>Email notifications</ui-switch>
    <ui-switch name="push" value="enabled">Push notifications</ui-switch>
    <div class="actions">
      <ui-button type="submit">Save</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<switch-form-demo></switch-form-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | boolean | `false` | Whether the switch is on. The attribute is the initial and reset state. |
| `value` | string | | Value submitted when on. Without it the form submits `on`. |
| `size` | `"default"` \| `"sm"` | `"default"` | Track and thumb size. |
| `disabled` | boolean | `false` | Disables the switch. Also true inside a disabled `<fieldset>`. |
| `aria-label` | string | | Accessible name when there is no visible text. Property name: `label`. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `checked` | boolean | Current state. Updated when the user toggles. Setting it moves the switch. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `change` | none | Bubbles from the element after the user toggles. `checked` is already updated. |
| `input` | none | The inner checkbox's native `input` event (composed). |

### Slots

| Slot | Description |
| --- | --- |
| (default) | The label text, rendered inside a native `<label>` for the switch. |

### CSS parts

| Part | Description |
| --- | --- |
| `control` | The inner `<input type="checkbox" role="switch">`. |
| `label` | The `<label>` around the slotted text. |

### CSS states

| State | Description |
| --- | --- |
| `:state(attr-checked)` | Set while the switch is on. |
| `:state(attr-size-is-sm)` | Set for the small size. |

### Forms

`ui-switch` is form-associated. When on it submits `value`, or `on` without one. When off it submits nothing.
`form.reset()` restores the `checked` attribute.

### Accessibility

The inner checkbox has `role="switch"` and `aria-checked`, so screen readers announce it as on or off. Space toggles
it and the host delegates focus to it. The slotted text labels it. Without text, use `aria-label`.


---

# Textarea

Source: http://realm.js.org/components/textarea/

`ui-textarea` wraps a native `<textarea>`. It starts at `rows` lines, grows with its content in browsers that support
`field-sizing: content`, and can be resized vertically. It is form-associated. Its `value` is submitted under its
`name`, and its validity is the inner textarea's validity.

```html live
<div class="demo-narrow">
  <ui-textarea aria-label="Message" placeholder="Type your message here."></ui-textarea>
</div>
```

## Examples

### With a label and description

```html live
<div class="demo-narrow">
  <ui-field>
    <ui-label for="textarea-bio">Bio</ui-label>
    <ui-textarea id="textarea-bio" rows="4" maxlength="160" placeholder="Tell us a little about yourself"></ui-textarea>
    <ui-field-description>Up to 160 characters.</ui-field-description>
  </ui-field>
</div>
```

### Disabled and read-only

```html live
<div class="demo-narrow demo-stack-tight">
  <ui-textarea aria-label="Disabled" placeholder="Disabled" disabled></ui-textarea>
  <ui-textarea aria-label="Release notes" value="Version 2.0 replaces the template syntax with native slots." readonly></ui-textarea>
</div>
```

### Invalid

`invalid` sets `aria-invalid` and a destructive border, for errors you detect yourself.

```html live
<div class="demo-narrow">
  <ui-textarea aria-label="Feedback" value="Too short" invalid></ui-textarea>
</div>
```

### Character count

Listen for `input` to react while the user types.

```html live
<custom-element name="textarea-count-demo">
  <script type="realm">
    const note = useState({ length: 0 });

    function typed(field) {
      note.length = field.value.length;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      width: 100%;
      max-width: calc(var(--spacing) * 96);
    }
    p {
      margin: 0;
      justify-self: end;
      font-size: var(--text-xs);
      color: var(--muted-foreground);
    }
  </style>

  <ui-textarea aria-label="Note" maxlength="200" placeholder="Write a note" oninput="typed(this)"></ui-textarea>
  <p><slot name="#note.length"></slot> / 200</p>
</custom-element>
<textarea-count-demo></textarea-count-demo>
```

### In a form

The text, including line breaks, is submitted under `name`. `required` and `minlength` block submission with the
browser's messages, and reset returns to the `value` attribute. Enter adds a new line and does not submit.

```html live
<custom-element name="textarea-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      result.text = [...new FormData(event.target)].map(([name, value]) => `${name}=${JSON.stringify(value)}`).join("\n");
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 96);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-textarea name="review" aria-label="Review" rows="3" minlength="10" required placeholder="What did you think?"></ui-textarea>
    <div class="actions">
      <ui-button type="submit">Post review</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<textarea-form-demo></textarea-form-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `""` | Current text. The attribute is the initial and reset value. |
| `placeholder` | string | | Placeholder text. |
| `rows` | number | `3` | Visible lines before the field grows. An integer of at least 1. |
| `minlength` | number | | Minimum length. |
| `maxlength` | number | | Maximum length. |
| `disabled` | boolean | `false` | Disables the textarea. Also true inside a disabled `<fieldset>`. |
| `readonly` | boolean | `false` | Makes the text read-only. |
| `required` | boolean | `false` | The form is invalid while the text is empty. |
| `invalid` | boolean | `false` | Sets `aria-invalid="true"` and the error style. Does not affect validity. |
| `aria-label` | string | | Accessible name, passed to the inner textarea. Property name: `label`. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `value` | string | Current text. Updated as the user types. Setting it updates the field. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `input` | none | The inner textarea's native `input` event (composed). |
| `change` | none | Dispatched from the element (bubbling) when the inner textarea fires `change`, after it loses focus. |

### CSS parts

| Part | Description |
| --- | --- |
| `textarea` | The inner native `<textarea>`. |

### Forms

`ui-textarea` is form-associated and submits `value` under its `name`. Validity is mirrored from the inner
textarea, so `required`, `minlength` and `maxlength` take part in `checkValidity()` and `reportValidity()`.
`form.reset()` restores the `value` attribute, and a disabled `<fieldset>` disables the field.

### Accessibility

The host delegates focus to the inner textarea. Name it with `aria-label`, `ui-label for` or a wrapping `<label>`.


---

# Toggle

Source: http://realm.js.org/components/toggle/

`ui-toggle` is a native `<button>` with `aria-pressed`. Each click flips its `pressed` state and fires `change`.
Use it for an on/off option that is shown as a button, such as bold in a text toolbar. For several toggles that share
one value, wrap them in a [Toggle Group](/components/toggle-group).

A toggle is not form-associated on its own and submits nothing. Inside a `ui-toggle-group` with a `name`, the group
submits the pressed values.

```html live
<ui-toggle aria-label="Bold">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M6 12h9a4 4 0 0 1 0 8H6V4h8a4 4 0 0 1 0 8" /></svg>
</ui-toggle>
```

## Examples

### Outline

```html live
<ui-toggle variant="outline" aria-label="Italic">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M19 4h-9M14 20H5M15 4 9 20" /></svg>
</ui-toggle>
```

### With text

```html live
<ui-toggle variant="outline">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M12 17v5M9 10.76V6h6v4.76l2 2.24v2H7v-2z" /><path d="M8 2h8" /></svg>
  Pin
</ui-toggle>
```

### Sizes

```html live
<ui-toggle size="sm" variant="outline">Small</ui-toggle>
<ui-toggle variant="outline">Default</ui-toggle>
<ui-toggle size="lg" variant="outline">Large</ui-toggle>
```

### Pressed and disabled

`pressed` sets the initial state and reflects to the attribute as the user toggles.

```html live
<ui-toggle pressed variant="outline">Pressed</ui-toggle>
<ui-toggle disabled variant="outline">Disabled</ui-toggle>
```

### Listening for changes

```html live
<custom-element name="toggle-change-demo">
  <script type="realm">
    const editor = useState({ wrap: "Line wrapping is off." });

    function changed(toggle) {
      editor.wrap = toggle.pressed ? "Line wrapping is on." : "Line wrapping is off.";
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 3);
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>

  <ui-toggle variant="outline" onchange="changed(this)">Wrap lines</ui-toggle>
  <p role="status"><slot name="#editor.wrap"></slot></p>
</custom-element>
<toggle-change-demo></toggle-change-demo>
```

### In a form

A lone toggle adds nothing to `FormData`. To submit toggles, put them in a `ui-toggle-group` with a `name` and give
each toggle a `value`.

```html live
<custom-element name="toggle-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      const entries = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`);
      result.text = entries.join("\n") || "(nothing submitted)";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: start;
    }
    .row {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)">
    <div class="row">
      <ui-toggle variant="outline" value="draft">Lone toggle</ui-toggle>
      <ui-toggle-group name="flags" type="multiple" aria-label="Flags">
        <ui-toggle variant="outline" value="pinned">Pinned</ui-toggle>
      </ui-toggle-group>
    </div>
    <ui-button type="submit">Submit</ui-button>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<toggle-form-demo></toggle-form-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `pressed` | boolean | `false` | Whether the toggle is pressed. Reflects to the attribute. |
| `variant` | `"default"` \| `"outline"` | `"default"` | Visual style. `outline` adds a border. |
| `size` | `"default"` \| `"sm"` \| `"lg"` | `"default"` | Height and padding. |
| `disabled` | boolean | `false` | Disables the button. |
| `value` | string | | Identifies the toggle inside a `ui-toggle-group`. |
| `aria-label` | string | | Accessible name, passed to the inner button. Use it for icon-only toggles. Property name: `label`. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `pressed` | boolean | Current state. Flipped by each click. Setting it updates the button. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `change` | none | Fired after each click, once `pressed` has flipped. Inside a `ui-toggle-group`, the group stops it and fires its own `change`. |

### Slots

| Slot | Description |
| --- | --- |
| (default) | The label and icons. Slotted `<svg>` elements are sized to `calc(var(--spacing) * 4)`. |

### CSS parts

| Part | Description |
| --- | --- |
| `button` | The inner native `<button>`. |

### CSS states and custom properties

| Name | Description |
| --- | --- |
| `:state(attr-pressed)` | Set while the toggle is pressed. |
| `:state(attr-variant-is-outline)`, `:state(attr-size-is-sm)`, `:state(attr-size-is-lg)` | Set for the current variant and size. |
| `--ui-radius-start`, `--ui-radius-end` | Override the start and end corner radii. Set by `ui-toggle-group` and `ui-button-group`. |

### Accessibility

The inner native button has `aria-pressed="true"` or `"false"`, so screen readers announce it as a toggle button.
Enter and Space toggle it, and the host delegates focus to the button.


---

# Toggle Group

Source: http://realm.js.org/components/toggle-group/

`ui-toggle-group` joins `ui-toggle` children into one control with a shared `value`. With `type="single"` at most one
toggle is pressed, like a segmented control. With `type="multiple"` any number can be pressed, like the bold,
italic and underline buttons of an editor. The `value` of each `ui-toggle` identifies it.

The group has the `group` role and moves focus between its toggles with the arrow keys. It is form-associated, and
the pressed values are submitted under its `name`, separated by commas.

```html live
<ui-toggle-group value="left" aria-label="Text alignment">
  <ui-toggle value="left" aria-label="Align left">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M3 6h18M3 12h10M3 18h14" /></svg>
  </ui-toggle>
  <ui-toggle value="center" aria-label="Align center">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M3 6h18M7 12h10M5 18h14" /></svg>
  </ui-toggle>
  <ui-toggle value="right" aria-label="Align right">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M3 6h18M11 12h10M7 18h14" /></svg>
  </ui-toggle>
</ui-toggle-group>
```

## Examples

### Multiple

With `type="multiple"`, each toggle is pressed independently and `value` lists every pressed toggle.

```html live
<ui-toggle-group type="multiple" value="bold,underline" aria-label="Text formatting">
  <ui-toggle value="bold" variant="outline" aria-label="Bold">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M6 12h9a4 4 0 0 1 0 8H6V4h8a4 4 0 0 1 0 8" /></svg>
  </ui-toggle>
  <ui-toggle value="italic" variant="outline" aria-label="Italic">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M19 4h-9M14 20H5M15 4 9 20" /></svg>
  </ui-toggle>
  <ui-toggle value="underline" variant="outline" aria-label="Underline">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M6 4v6a6 6 0 0 0 12 0V4M4 20h16" /></svg>
  </ui-toggle>
</ui-toggle-group>
```

### Outline segmented control

Outline toggles with text make a segmented control. In single mode, clicking the pressed toggle again unpresses it
and the value becomes empty.

```html live
<ui-toggle-group value="week" aria-label="Range">
  <ui-toggle value="day" variant="outline">Day</ui-toggle>
  <ui-toggle value="week" variant="outline">Week</ui-toggle>
  <ui-toggle value="month" variant="outline">Month</ui-toggle>
</ui-toggle-group>
```

### Listening for changes

The group fires `change` after every click. Read the new `value` from the group. The toggles' own `change` events
stop at the group.

```html live
<custom-element name="toggle-group-change-demo">
  <script type="realm">
    const view = useState({ mode: "grid" });

    function changed(group) {
      view.mode = group.value || "none";
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 3);
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>

  <ui-toggle-group value="grid" aria-label="View" onchange="changed(this)">
    <ui-toggle value="list" variant="outline" size="sm">List</ui-toggle>
    <ui-toggle value="grid" variant="outline" size="sm">Grid</ui-toggle>
    <ui-toggle value="board" variant="outline" size="sm">Board</ui-toggle>
  </ui-toggle-group>
  <p>View: <slot name="#view.mode"></slot></p>
</custom-element>
<toggle-group-change-demo></toggle-group-change-demo>
```

### In a form

The group submits `value` under its `name`: one value in single mode, a comma-separated list in multiple mode, or an
empty string when nothing is pressed. Reset returns to the `value` attribute.

```html live
<custom-element name="toggle-group-form-demo">
  <script type="realm">
    const result = useState({ text: "Submit the form to see its data." });

    function submit(event) {
      event.preventDefault();
      result.text = [...new FormData(event.target)].map(([name, value]) => `${name}=${value}`).join("\n");
    }

    function reset() {
      result.text = "The form was reset.";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: 100%;
      max-width: calc(var(--spacing) * 80);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: start;
    }
    .actions {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    output {
      display: block;
      box-sizing: border-box;
      width: 100%;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-family: var(--font-mono);
      font-size: var(--text-xs);
      white-space: pre-wrap;
    }
  </style>

  <form onsubmit="submit(event)" onreset="reset()">
    <ui-toggle-group name="size" value="m" aria-label="Size">
      <ui-toggle value="s" variant="outline">S</ui-toggle>
      <ui-toggle value="m" variant="outline">M</ui-toggle>
      <ui-toggle value="l" variant="outline">L</ui-toggle>
    </ui-toggle-group>
    <ui-toggle-group name="toppings" type="multiple" aria-label="Toppings">
      <ui-toggle value="cheese" variant="outline">Cheese</ui-toggle>
      <ui-toggle value="olives" variant="outline">Olives</ui-toggle>
      <ui-toggle value="basil" variant="outline">Basil</ui-toggle>
    </ui-toggle-group>
    <div class="actions">
      <ui-button type="submit">Order</ui-button>
      <ui-button type="reset" variant="outline">Reset</ui-button>
    </div>
  </form>
  <output><slot name="#result.text"></slot></output>
</custom-element>
<toggle-group-form-demo></toggle-group-form-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"single"` \| `"multiple"` | `"single"` | Whether one or several toggles can be pressed. |
| `value` | string | `""` | Pressed toggle values, separated by commas. The attribute is the initial and reset value. |
| `orientation` | `"horizontal"` \| `"vertical"` | `"horizontal"` | Layout direction, and which arrow keys move focus. |

### Properties

| Property | Type | Description |
| --- | --- | --- |
| `value` | string | Pressed values as a comma-separated string. Setting it presses the matching toggles. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `change` | none | Fired after a toggle in the group is clicked and `value` is updated. |

### Slots

| Slot | Description |
| --- | --- |
| (default) | The `ui-toggle` elements. Every child except the first gets `--ui-radius-start: 0`, and every child except the last gets `--ui-radius-end: 0`. |

### Child elements

| Element | Attributes read | Description |
| --- | --- | --- |
| `ui-toggle` | `value`, `pressed` | The group sets each toggle's `pressed` from its own `value`. A toggle's value must not contain a comma. |

### CSS parts

| Part | Description |
| --- | --- |
| `group` | The `display: contents` wrapper that carries the `focusgroup` attribute. |

### CSS states

| State | Description |
| --- | --- |
| `:state(attr-orientation-is-vertical)` | Set for the vertical layout. |

### Forms

`ui-toggle-group` is form-associated and submits `value` under its `name`, including an empty string when nothing
is pressed. `form.reset()` restores the `value` attribute and the pressed toggles follow it. The group has no
`disabled` attribute. Disable individual toggles instead.

### Accessibility

The host has `role="group"`. Name it with `aria-label`. Each toggle is a button with `aria-pressed`. The toggles
form a native `focusgroup`. The arrow keys (Left and Right, or Up and Down when vertical) move focus between them,
wrapping at the ends, and Home and End jump to the first and last toggle. Space or Enter presses the focused toggle.


---

# Alert

Source: http://realm.js.org/components/alert/

`ui-alert` shows a short message in a bordered box, with an optional icon on the left and `ui-alert-title` and
`ui-alert-description` stacked beside it. The element has the ARIA role `alert`, so screen readers
announce it when it is added to the page. It fills the width of its container.

```html live
<div class="demo-medium">
  <ui-alert>
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="m9 12 2 2 4-4"/></svg>
    <ui-alert-title>Changes saved</ui-alert-title>
    <ui-alert-description>Your profile was updated. It can take a minute to show everywhere.</ui-alert-description>
  </ui-alert>
</div>
```

## Examples

### Destructive

Use `variant="destructive"` for errors. The title and icon switch to the destructive colour and the description
takes a tint of it.

```html live
<div class="demo-medium">
  <ui-alert variant="destructive">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" x2="12" y1="8" y2="12"/><line x1="12" x2="12.01" y1="16" y2="16"/></svg>
    <ui-alert-title>Payment failed</ui-alert-title>
    <ui-alert-description>Your card was declined. Check the card details and try again.</ui-alert-description>
  </ui-alert>
</div>
```

### Without an icon

The icon is optional. The title and description keep their column.

```html live
<div class="demo-medium">
  <ui-alert>
    <ui-alert-title>Scheduled maintenance</ui-alert-title>
    <ui-alert-description>The dashboard will be read-only on Sunday from 02:00 to 03:00 UTC.</ui-alert-description>
  </ui-alert>
</div>
```

### Title only

```html live
<div class="demo-medium">
  <ui-alert>
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>
    <ui-alert-title>A new version is available. Reload to update.</ui-alert-title>
  </ui-alert>
</div>
```

### Rich description

`ui-alert-description` is a grid, so paragraphs and lists inside it stack with a small gap.

```html live
<div class="demo-medium">
  <ui-alert variant="destructive">
    <ui-alert-title>Unable to process your payment</ui-alert-title>
    <ui-alert-description>
      <p class="demo-text">Please verify your billing information:</p>
      <ul>
        <li>Check the card number</li>
        <li>Make sure the billing address matches</li>
      </ul>
    </ui-alert-description>
  </ui-alert>
</div>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-alert` | | The bordered box. A two-column grid: a leading `<svg>` icon in the first column, everything else in the second. |
| `<svg>` | (default) | Optional icon as a direct child of `ui-alert`. Sized to `calc(var(--spacing) * 4)` and spans the title and description rows. |
| `ui-alert-title` | (default) | The heading line, in medium weight. |
| `ui-alert-description` | (default) | Muted text under the title (tinted destructive in the destructive variant). A grid, so `<p>` and `<ul>` stack. |

Each part has a single default slot that takes any content.

### ui-alert attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default"` \| `"destructive"` | `"default"` | Colour scheme of the alert. |

### Accessibility

The element has the implicit role `alert` (set through `ElementInternals`), which makes it a live region.
Screen readers read its content when it is inserted. This is usually harmless for content present on page load, but
avoid putting many alerts on one page.


---

# Avatar

Source: http://realm.js.org/components/avatar/

`ui-avatar` is a small circle with a `ui-avatar-image` and a `ui-avatar-fallback` inside. The fallback, usually
initials or an icon, is shown until the image has loaded and again when it fails to load. Without an image only the
fallback is shown.

```html live
<div class="demo-row">
  <ui-avatar>
    <ui-avatar-image src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' fill='%236366f1'/%3E%3Ccircle cx='32' cy='26' r='12' fill='%23e0e7ff'/%3E%3Cpath d='M10 60c4-14 14-20 22-20s18 6 22 20' fill='%23e0e7ff'/%3E%3C/svg%3E" alt="Ada Lovelace"></ui-avatar-image>
    <ui-avatar-fallback>AL</ui-avatar-fallback>
  </ui-avatar>
  <ui-avatar>
    <ui-avatar-fallback>CN</ui-avatar-fallback>
  </ui-avatar>
</div>
```

## Examples

### Fallback

When the image cannot be loaded, the fallback is shown and the broken image is removed.

```html live
<ui-avatar>
  <ui-avatar-image src="data:image/png;base64,broken" alt="Grace Hopper"></ui-avatar-image>
  <ui-avatar-fallback>GH</ui-avatar-fallback>
</ui-avatar>
```

### Sizes

`size` is `sm` (24px), `default` (32px) or `lg` (40px). The small size uses `var(--text-xs)` for the fallback, so
keep it to one or two letters.

```html live
<div class="demo-row">
  <ui-avatar size="sm"><ui-avatar-fallback>S</ui-avatar-fallback></ui-avatar>
  <ui-avatar><ui-avatar-fallback>MD</ui-avatar-fallback></ui-avatar>
  <ui-avatar size="lg"><ui-avatar-fallback>LG</ui-avatar-fallback></ui-avatar>
</div>
```

### Square

`shape="square"` uses `var(--radius-md)` instead of a circle, for an organisation or project logo.

```html live
<ui-avatar shape="square"><ui-avatar-fallback>AC</ui-avatar-fallback></ui-avatar>
```

### Group

`ui-avatar-group` overlaps its children and draws a ring in the background colour around each one.
`ui-avatar-group-count` is a muted circle for the number of people not shown.

```html live
<ui-avatar-group aria-label="Reviewers">
  <ui-avatar><ui-avatar-fallback>AL</ui-avatar-fallback></ui-avatar>
  <ui-avatar><ui-avatar-fallback>GH</ui-avatar-fallback></ui-avatar>
  <ui-avatar><ui-avatar-fallback>KJ</ui-avatar-fallback></ui-avatar>
  <ui-avatar-group-count>+3</ui-avatar-group-count>
</ui-avatar-group>
```

### In a list

```html live
<div class="demo-stack">
  <div class="demo-row-tight">
    <ui-avatar><ui-avatar-fallback>OM</ui-avatar-fallback></ui-avatar>
    <div>
      <p class="demo-text">Olivia Martin</p>
      <p class="demo-muted">olivia.martin@email.com</p>
    </div>
  </div>
  <div class="demo-row-tight">
    <ui-avatar><ui-avatar-fallback>JL</ui-avatar-fallback></ui-avatar>
    <div>
      <p class="demo-text">Jackson Lee</p>
      <p class="demo-muted">jackson.lee@email.com</p>
    </div>
  </div>
</div>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-avatar` | (root) | The circle (or rounded square) that clips its content. |
| `ui-avatar-image` | (default) | The `<img>`, hidden until it has loaded and removed when loading fails. |
| `ui-avatar-fallback` | (default) | Initials or an icon on a muted background, shown until the image loads and when it fails. |
| `ui-avatar-group` | (root) | A row that overlaps its avatars, each with a ring in the background colour. |
| `ui-avatar-group-count` | (default) | A muted 32px circle for a count such as "+3", inside `ui-avatar-group`. |

The default slot of each part takes any content.

### Attributes

#### ui-avatar

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` | 24px, 32px or 40px square. |
| `shape` | `"circle"` \| `"square"` | `"circle"` | `square` uses `var(--radius-md)` corners. |

#### ui-avatar-image

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | string | | Image URL. |
| `alt` | string | `""` | Alternative text for the image. |

### CSS parts

| Part | Element | Description |
| --- | --- | --- |
| `image` | `ui-avatar-image` | The `<img>`. |
| `fallback` | `ui-avatar-fallback` | The `<span>` around the fallback content. |

### Accessibility

Give `alt` a name when the avatar is the only thing identifying a person. When the name is already shown next to
the avatar, leave `alt` empty so screen readers skip the image. The fallback text is read as normal text.
`ui-avatar-group` has `role="group"`. Name it with `aria-label` when the group needs a label.


---

# Badge

Source: http://realm.js.org/components/badge/

`ui-badge` is an inline label with a filled or outlined background. It has no behaviour of its own. Put it next to
the text it describes, or inside a link or button when it should be interactive.

```html live
<ui-badge>Badge</ui-badge>
<ui-badge variant="secondary">Secondary</ui-badge>
<ui-badge variant="destructive">Destructive</ui-badge>
<ui-badge variant="outline">Outline</ui-badge>
```

## Examples

### With an icon

A slotted `<svg>` is sized to `calc(var(--spacing) * 3)`.

```html live
<ui-badge variant="secondary">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>
  Verified
</ui-badge>
<ui-badge variant="outline">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 6v6l4 2"/></svg>
  Pending
</ui-badge>
```

### Shapes

`shape="pill"` rounds the ends fully. `shape="round"` makes a 20px circle for counts, with tabular numbers so
the width stays steady as the count changes.

```html live
<ui-badge shape="pill">Pill</ui-badge>
<ui-badge variant="secondary" shape="pill">Beta</ui-badge>
<ui-badge shape="round">8</ui-badge>
<ui-badge variant="destructive" shape="round">99</ui-badge>
<ui-badge variant="outline" shape="round">20+</ui-badge>
```

### As a link

Wrap the badge in an `<a>` to make it a link. The badge itself has no interactive behaviour.

```html live
<a href="#badge"><ui-badge variant="outline">#release-notes</ui-badge></a>
```

### Status from state

Bind `variant` with `_variant` to pick the style from component state, using a lookup table.

```html live
<custom-element name="badge-status-demo">
  <script type="realm">
    const VARIANTS = { paid: "default", pending: "secondary", failed: "destructive" };

    const order = useState({
      status: "pending",
      get variant() {
        return VARIANTS[this.status];
      },
    });

    function cycle() {
      const statuses = Object.keys(VARIANTS);
      order.status = statuses[(statuses.indexOf(order.status) + 1) % statuses.length];
    }
  </script>
  <style type="realm">
    :host {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 3);
    }
  </style>
  <ui-badge _variant="#order.variant"><slot name="#order.status"></slot></ui-badge>
  <ui-button size="sm" variant="outline" onclick="cycle()">Next status</ui-button>
</custom-element>
<badge-status-demo></badge-status-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-badge` | (default) | An inline label. Its default slot takes any content: text and an optional `<svg>` icon. |

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default"` \| `"secondary"` \| `"destructive"` \| `"outline"` | `"default"` | Colour scheme of the badge. |
| `shape` | `"default"` \| `"pill"` \| `"round"` | `"default"` | `pill` is fully rounded. `round` is a 20px circle for counts, with tabular numbers. |

### CSS parts

None. The badge renders only a slot, so style the element itself.

### Accessibility

The badge has no role and is read as plain text. If the colour carries meaning (for example red for failed),
make sure the text says the same thing.


---

# Card

Source: http://realm.js.org/components/card/

`ui-card` is a bordered, rounded panel. You build it from parts: `ui-card-header` (with `ui-card-title`,
`ui-card-description` and an optional `ui-card-action`), `ui-card-content` and `ui-card-footer`. Every part goes in
the default slot, in source order, and takes any content.

```html live
<div class="demo-narrow">
  <ui-card>
    <ui-card-header>
      <ui-card-title>Create project</ui-card-title>
      <ui-card-description>Deploy your new project in one click.</ui-card-description>
    </ui-card-header>
    <ui-card-content>
      <ui-field>
        <ui-label for="card-project-name">Name</ui-label>
        <ui-input id="card-project-name" placeholder="Name of your project"></ui-input>
      </ui-field>
    </ui-card-content>
    <ui-card-footer justify="between">
      <ui-button variant="outline">Cancel</ui-button>
      <ui-button>Deploy</ui-button>
    </ui-card-footer>
  </ui-card>
</div>
```

## Examples

### Header action

`ui-card-action` holds a button, badge or menu. It sits to the right of the title and description and spans both
rows.

```html live
<div class="demo-narrow">
  <ui-card>
    <ui-card-header>
      <ui-card-title>Notifications</ui-card-title>
      <ui-card-description>You have 3 unread messages.</ui-card-description>
      <ui-card-action><ui-button variant="ghost" size="sm">Mark all read</ui-button></ui-card-action>
    </ui-card-header>
    <ui-card-content>
      <p class="demo-text">Your call has been confirmed for Friday at 10:00.</p>
    </ui-card-content>
  </ui-card>
</div>
```

### Stat card

A card does not need a title. Use only a description and the content for a compact metric.

```html live
<div class="demo-narrow">
  <ui-card>
    <ui-card-header>
      <ui-card-description>Total revenue</ui-card-description>
      <ui-card-action><ui-badge variant="outline">+20.1%</ui-badge></ui-card-action>
    </ui-card-header>
    <ui-card-content>
      <p class="demo-value">$45,231.89</p>
    </ui-card-content>
  </ui-card>
</div>
```

### Login form

The content can hold a whole form. `orientation="vertical"` on the footer stacks its children and stretches them to
the full width, which suits a single submit button.

```html live
<div class="demo-narrow">
  <ui-card>
    <ui-card-header>
      <ui-card-title>Log in to your account</ui-card-title>
      <ui-card-description>Enter your email below to log in.</ui-card-description>
      <ui-card-action><ui-button variant="link">Sign up</ui-button></ui-card-action>
    </ui-card-header>
    <ui-card-content>
      <form id="card-login" onsubmit="event.preventDefault()">
        <ui-field-group>
          <ui-field>
            <ui-label for="card-email">Email</ui-label>
            <ui-input id="card-email" name="email" type="email" placeholder="m@example.com"></ui-input>
          </ui-field>
          <ui-field>
            <ui-label for="card-password">Password</ui-label>
            <ui-input id="card-password" name="password" type="password"></ui-input>
          </ui-field>
        </ui-field-group>
      </form>
    </ui-card-content>
    <ui-card-footer orientation="vertical">
      <ui-button type="submit" form="card-login">Login</ui-button>
      <ui-button variant="outline">Login with Google</ui-button>
    </ui-card-footer>
  </ui-card>
</div>
```

### Repeated from state

Cards are often rendered from a list with `<repeat-list>`.

```html live
<custom-element name="card-stats-demo">
  <script type="realm">
    const dashboard = useState({
      stats: [
        { id: "revenue", label: "Revenue", value: "$45,231", change: "+20.1% from last month" },
        { id: "subscriptions", label: "Subscriptions", value: "+2,350", change: "+180.1% from last month" },
        { id: "active", label: "Active now", value: "+573", change: "+201 since last hour" },
      ],
    });
  </script>
  <style type="realm">
    :host {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(calc(var(--spacing) * 48), 1fr));
      gap: calc(var(--spacing) * 4);
      width: 100%;
    }
    .value {
      margin: 0;
      font-size: var(--text-2xl);
      font-weight: var(--font-weight-bold);
    }
    .change {
      margin: calc(var(--spacing) * 1) 0 0;
      font-size: var(--text-xs);
      color: var(--muted-foreground);
    }
  </style>
  <repeat-list of="#dashboard.stats" as="stat" key="id">
    <ui-card>
      <ui-card-header>
        <ui-card-description><slot name="#stat.label"></slot></ui-card-description>
      </ui-card-header>
      <ui-card-content>
        <p class="value"><slot name="#stat.value"></slot></p>
        <p class="change"><slot name="#stat.change"></slot></p>
      </ui-card-content>
    </ui-card>
  </repeat-list>
</custom-element>
<card-stats-demo></card-stats-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-card` | | The bordered panel. A flex column with a gap between its parts. Fills its container's width. |
| `ui-card-header` | (default) | A grid for the title, description and action, with horizontal padding. |
| `ui-card-title` | (default) | A heading (level 3 unless `level` says otherwise) in `var(--text-base)` semibold. Place it in `ui-card-header`. |
| `ui-card-description` | (default) | Supporting text in muted `var(--text-sm)`. Place it in `ui-card-header`. |
| `ui-card-action` | (default) | Content in the header's second column, aligned to the end and spanning the title and description rows. |
| `ui-card-content` | (default) | The body, with horizontal padding. |
| `ui-card-footer` | (default) | A row of actions at the bottom, with a gap and horizontal padding. |

Every part has a single default slot that takes any content.

### ui-card-title attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `level` | number (1 to 6) | `3` | The heading level. Use `1` for a card that is the page's main content and `2` for cards directly under the page heading. |

### ui-card-footer attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `justify` | `"between"` \| `"end"` | | Spreads the children apart, or pushes them to the end. Without it they start at the left. |
| `orientation` | `"vertical"` | | Stacks the children and stretches them to the full width. |

The other parts have no attributes.

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-card-title` | `title` | The heading element (`role="heading"` with `aria-level`) around the title text. |

### Accessibility

The card has no role. `ui-card-title` renders a heading, level 3 by default, so the card shows up in the document
outline. Set `level` so the heading follows the page's outline without skipping levels. Wrap the
card in `<article>` or `<section>` when it represents a standalone item.


---

# Chart

Source: http://realm.js.org/components/chart/

`ui-chart` draws a responsive SVG chart from `data`, a list of plain objects. `x` names the field used for the
category labels along the bottom, and `y` names one or more numeric fields to plot. It supports bars, lines and
filled areas, a value grid with five ticks, and a legend when there is more than one series. Series colours come
from the theme tokens `--chart-1` to `--chart-5`. The chart is as wide as its container.

```html live
<ui-chart x="month" y="desktop" label="Desktop visitors per month"
  data='[{"month":"Jan","desktop":186},{"month":"Feb","desktop":305},{"month":"Mar","desktop":237},{"month":"Apr","desktop":73},{"month":"May","desktop":209},{"month":"Jun","desktop":214}]'>
</ui-chart>
```

## Examples

### Several series

List several fields in `y`, separated by commas. Bars are grouped per category and a legend appears under the
chart.

```html live
<ui-chart x="month" y="desktop,mobile" label="Visitors per month by device"
  data='[{"month":"Jan","desktop":186,"mobile":80},{"month":"Feb","desktop":305,"mobile":200},{"month":"Mar","desktop":237,"mobile":120},{"month":"Apr","desktop":73,"mobile":190},{"month":"May","desktop":209,"mobile":130},{"month":"Jun","desktop":214,"mobile":140}]'>
</ui-chart>
```

### Line

```html live
<ui-chart type="line" x="month" y="desktop,mobile" label="Visitors per month by device"
  data='[{"month":"Jan","desktop":186,"mobile":80},{"month":"Feb","desktop":305,"mobile":200},{"month":"Mar","desktop":237,"mobile":120},{"month":"Apr","desktop":73,"mobile":190},{"month":"May","desktop":209,"mobile":130},{"month":"Jun","desktop":214,"mobile":140}]'>
</ui-chart>
```

### Area

`type="area"` draws the line with a translucent fill underneath.

```html live
<ui-chart type="area" x="month" y="desktop" label="Desktop visitors per month"
  data='[{"month":"Jan","desktop":186},{"month":"Feb","desktop":305},{"month":"Mar","desktop":237},{"month":"Apr","desktop":73},{"month":"May","desktop":209},{"month":"Jun","desktop":214}]'>
</ui-chart>
```

### Height

`height` sets the height of the drawing in SVG units (the width is always 600 units). The chart scales to the
width of its container and keeps that ratio, so a smaller `height` gives a flatter chart.

```html live
<ui-chart height="120" label="Weekly sales"
  data='[{"label":"Mon","value":12},{"label":"Tue","value":18},{"label":"Wed","value":9},{"label":"Thu","value":22},{"label":"Fri","value":30}]'>
</ui-chart>
```

The last example also relies on the defaults `x="label"` and `y="value"`.

### Data from component state

Bind `data`, `y` or `type` from state with `_data`, `_y` and `_type`. The chart redraws when the state changes.
This card switches the series and the chart type with lookup tables, and generates new data on demand.

```html live
<custom-element name="chart-visitors-demo">
  <script type="realm">
    const SERIES = { all: "desktop,mobile", desktop: "desktop", mobile: "mobile" };
    const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"];

    const visitors = useState({
      series: "all",
      type: "bar",
      months: MONTHS.map((month, index) => ({ month, desktop: 120 + index * 30, mobile: 200 - index * 20 })),
      get y() {
        return SERIES[this.series];
      },
    });

    function pickSeries(event) {
      visitors.series = event.target.value;
    }

    function pickType(event) {
      visitors.type = event.target.value;
    }

    function shuffle() {
      visitors.months = MONTHS.map((month) => ({
        month,
        desktop: Math.round(50 + Math.random() * 300),
        mobile: Math.round(50 + Math.random() * 300),
      }));
    }
  </script>
  <style type="realm">
    :host {
      display: block;
      width: 100%;
    }
    .controls {
      display: flex;
      flex-wrap: wrap;
      gap: calc(var(--spacing) * 2);
      margin-bottom: calc(var(--spacing) * 4);
    }
  </style>
  <ui-card>
    <ui-card-header>
      <ui-card-title>Visitors</ui-card-title>
      <ui-card-description>January to June</ui-card-description>
      <ui-card-action><ui-button size="sm" variant="outline" onclick="shuffle()">New data</ui-button></ui-card-action>
    </ui-card-header>
    <ui-card-content>
      <div class="controls">
        <select aria-label="Series" onchange="pickSeries(event)">
          <option value="all">Desktop and mobile</option>
          <option value="desktop">Desktop</option>
          <option value="mobile">Mobile</option>
        </select>
        <select aria-label="Chart type" onchange="pickType(event)">
          <option value="bar">Bar</option>
          <option value="line">Line</option>
          <option value="area">Area</option>
        </select>
      </div>
      <ui-chart x="month" _y="#visitors.y" _type="#visitors.type" _data="#visitors.months" label="Visitors per month"></ui-chart>
    </ui-card-content>
  </ui-card>
</custom-element>
<chart-visitors-demo></chart-visitors-demo>
```

### Custom colours

Each series uses `var(--chart-1)`, `var(--chart-2)` and so on, cycling after five. Override the tokens on a
wrapping element to recolour the chart.

```html live
<div class="demo-full" style="--chart-1: var(--primary); --chart-2: var(--muted-foreground)">
<ui-chart x="quarter" y="revenue,costs" label="Revenue and costs per quarter"
  data='[{"quarter":"Q1","revenue":420,"costs":310},{"quarter":"Q2","revenue":510,"costs":330},{"quarter":"Q3","revenue":480,"costs":360},{"quarter":"Q4","revenue":620,"costs":390}]'>
</ui-chart>
</div>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"bar"` \| `"line"` \| `"area"` | `"bar"` | How the series are drawn. |
| `data` | array of objects | `[]` | The data points, one object per category. Accepts JSON in the attribute, or an array through the `data` property or a `_data` binding. |
| `x` | string | `"label"` | Field used for the category labels on the horizontal axis. |
| `y` | string | `"value"` | Field, or comma-separated fields, plotted as series. Non-numeric values count as `0`. |
| `height` | number | `240` | Height of the drawing in SVG units, minimum `80`. The width is 600 units and the chart scales to its container. |
| `label` | string | `"Chart"` | Accessible name of the chart image. |

### Parts

`ui-chart` has no child parts and no slots. It draws everything from its attributes.

### CSS parts

| Part | Description |
| --- | --- |
| `svg` | The chart `<svg>`. |
| `legend` | The legend under the chart. It has content only when `y` names more than one series. |

### CSS custom properties

| Property | Description |
| --- | --- |
| `--chart-1` … `--chart-5` | Series colours, in order. Defined in `theme.css`. Override them on an ancestor, such as a wrapping `<div>`. |

The axis labels use the element's `color` (muted foreground by default) and the grid lines use `var(--border)`.

### Accessibility

The SVG has `role="img"` and its accessible name comes from `label`, so describe what the chart shows. Each bar
has a `<title>` with its category, series and value, shown as a native tooltip on hover. The data is not
available as a table to screen readers. When the numbers matter, put a `ui-table` with the same data next to the
chart.


---

# Empty

Source: http://realm.js.org/components/empty/

`ui-empty` fills the space where content would be when there is none yet. It is a dashed, centred box built from
parts: `ui-empty-header` holds optional `ui-empty-media`, a `ui-empty-title` and a `ui-empty-description`, and
`ui-empty-content` holds the actions underneath. It has no role of its own.

```html live
<div class="demo-full">
  <ui-empty>
    <ui-empty-header>
      <ui-empty-media variant="icon">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z"/></svg>
      </ui-empty-media>
      <ui-empty-title>No projects yet</ui-empty-title>
      <ui-empty-description>You have not created any projects. Get started by creating your first one.</ui-empty-description>
    </ui-empty-header>
    <ui-empty-content>
      <div class="demo-row-tight">
        <ui-button>Create project</ui-button>
        <ui-button variant="outline">Import project</ui-button>
      </div>
    </ui-empty-content>
  </ui-empty>
</div>
```

## Examples

### Without media

Leave out `ui-empty-media` for a text-only empty state.

```html live
<div class="demo-full">
  <ui-empty>
    <ui-empty-header>
      <ui-empty-title>No results</ui-empty-title>
      <ui-empty-description>Try a different search term or clear the filters.</ui-empty-description>
    </ui-empty-header>
    <ui-empty-content>
      <ui-button variant="outline" size="sm">Clear filters</ui-button>
    </ui-empty-content>
  </ui-empty>
</div>
```

### With an avatar

Without `variant`, `ui-empty-media` is a plain wrapper, so an avatar or an avatar group keeps its own look.

```html live
<div class="demo-full">
  <ui-empty>
    <ui-empty-header>
      <ui-empty-media>
        <ui-avatar size="lg"><ui-avatar-fallback>LR</ui-avatar-fallback></ui-avatar>
      </ui-empty-media>
      <ui-empty-title>User offline</ui-empty-title>
      <ui-empty-description>This user is currently offline. You can leave a message to notify them.</ui-empty-description>
    </ui-empty-header>
    <ui-empty-content>
      <ui-button size="sm">Leave a message</ui-button>
    </ui-empty-content>
  </ui-empty>
</div>
```

### With an input

`ui-empty-content` is a centred column capped at `calc(var(--spacing) * 96)`, so it also fits a search box and a
note.

```html live
<div class="demo-full">
  <ui-empty>
    <ui-empty-header>
      <ui-empty-title>404 - Not found</ui-empty-title>
      <ui-empty-description>The page you are looking for does not exist. Try searching for what you need.</ui-empty-description>
    </ui-empty-header>
    <ui-empty-content>
      <div class="demo-full">
        <ui-input type="search" aria-label="Search pages" placeholder="Search pages"></ui-input>
      </div>
      <p class="demo-muted">Need help? <a href="#">Contact support</a></p>
    </ui-empty-content>
  </ui-empty>
</div>
```

### Shown when a list is empty

Switch between the list and the empty state with `<is-visible>` and `<is-hidden>`.

```html live
<custom-element name="empty-inbox-demo">
  <script type="realm">
    const inbox = useState({
      messages: [
        { id: 1, subject: "Weekly report" },
        { id: 2, subject: "Invoice INV-204" },
      ],
      get empty() {
        return this.messages.length === 0;
      },
    });

    function archive(message) {
      inbox.messages = inbox.messages.filter((item) => item.id !== message.id);
    }

    function restore() {
      inbox.messages = [
        { id: 1, subject: "Weekly report" },
        { id: 2, subject: "Invoice INV-204" },
      ];
    }
  </script>
  <style type="realm">
    :host {
      display: block;
      width: 100%;
    }
    ul {
      display: grid;
      gap: calc(var(--spacing) * 2);
      margin: 0;
      padding: 0;
      list-style: none;
    }
    li {
      display: flex;
      align-items: center;
      justify-content: space-between;
      padding: calc(var(--spacing) * 2) calc(var(--spacing) * 3);
      border: 1px solid var(--border);
      border-radius: var(--radius-md);
      font-size: var(--text-sm);
    }
  </style>
  <is-hidden when="#inbox.empty">
    <ul>
      <li repeat="#inbox.messages" as="message" key="id">
        <slot name="#message.subject"></slot>
        <ui-button size="sm" variant="ghost" onclick="archive(message)">Archive</ui-button>
      </li>
    </ul>
  </is-hidden>
  <is-visible when="#inbox.empty">
    <ui-empty>
      <ui-empty-header>
        <ui-empty-title>Inbox zero</ui-empty-title>
        <ui-empty-description>Every message has been archived.</ui-empty-description>
      </ui-empty-header>
      <ui-empty-content>
        <ui-button size="sm" variant="outline" onclick="restore()">Restore messages</ui-button>
      </ui-empty-content>
    </ui-empty>
  </is-visible>
</custom-element>
<empty-inbox-demo></empty-inbox-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-empty` | | The dashed, centred box. A flex column with a gap between header and content. |
| `ui-empty-header` | (default) | A centred column for media, title and description, capped at `calc(var(--spacing) * 96)`. |
| `ui-empty-media` | (default) | A wrapper above the title for an icon, avatar or image. Place it in `ui-empty-header`. |
| `ui-empty-title` | (default) | A heading (level 3 unless `level` says otherwise) in `var(--text-lg)`. Place it in `ui-empty-header`. |
| `ui-empty-description` | (default) | Supporting text in muted `var(--text-sm)`. Place it in `ui-empty-header`. |
| `ui-empty-content` | (default) | Actions or inputs under the header, in a centred column capped at `calc(var(--spacing) * 96)`. |

Every part has a single default slot that takes any content.

### ui-empty-media attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"icon"` | | Shows the content in a muted, rounded `calc(var(--spacing) * 10)` square. Without it the media is a plain wrapper. |

A slotted `<svg>` is sized to `calc(var(--spacing) * 6)`.

### ui-empty-title attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `level` | number, 1 to 6 | `3` | The heading level, so the title fits the page outline. |

The other parts have no attributes.

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-empty-title` | `title` | The heading around the title text. |

### Accessibility

The element has no role. `ui-empty-title` is a heading with `aria-level` from `level` (3 by default). If the empty state appears after a user action
(such as a search), consider announcing it with a live region of your own.


---

# Item

Source: http://realm.js.org/components/item/

`ui-item` lays out one row of content from parts, in source order: optional `ui-item-media` on the left,
`ui-item-content` (with `ui-item-title` and `ui-item-description`) filling the middle, and `ui-item-actions` on the
right. `ui-item-group` stacks items in a column and gives the group the ARIA role `list`.

```html live
<div class="demo-medium">
  <ui-item variant="outline">
    <ui-item-content>
      <ui-item-title>Basic item</ui-item-title>
      <ui-item-description>A simple item with a title and a description.</ui-item-description>
    </ui-item-content>
    <ui-item-actions>
      <ui-button variant="outline" size="sm">Action</ui-button>
    </ui-item-actions>
  </ui-item>
</div>
```

## Examples

### Variants

`default` has no border or background, `outline` adds a border, `muted` a subtle background.

```html live
<div class="demo-medium demo-stack">
  <ui-item>
    <ui-item-content>
      <ui-item-title>Default</ui-item-title>
      <ui-item-description>Transparent background and border.</ui-item-description>
    </ui-item-content>
  </ui-item>
  <ui-item variant="outline">
    <ui-item-content>
      <ui-item-title>Outline</ui-item-title>
      <ui-item-description>A visible border.</ui-item-description>
    </ui-item-content>
  </ui-item>
  <ui-item variant="muted">
    <ui-item-content>
      <ui-item-title>Muted</ui-item-title>
      <ui-item-description>A muted background.</ui-item-description>
    </ui-item-content>
  </ui-item>
</div>
```

### Small

`size="sm"` reduces the padding and gap. An `<svg>` in `ui-item-media` is sized to `calc(var(--spacing) * 4)`.

```html live
<div class="demo-medium">
  <ui-item variant="outline" size="sm">
    <ui-item-media>
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>
    </ui-item-media>
    <ui-item-content>
      <ui-item-title>Your profile has been verified.</ui-item-title>
    </ui-item-content>
    <ui-item-actions>
      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6"/></svg>
    </ui-item-actions>
  </ui-item>
</div>
```

### Icon media

`variant="icon"` puts the icon in a small bordered, muted box.

```html live
<div class="demo-medium">
  <ui-item variant="outline">
    <ui-item-media variant="icon">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"/></svg>
    </ui-item-media>
    <ui-item-content>
      <ui-item-title>Security alert</ui-item-title>
      <ui-item-description>New login detected from an unknown device.</ui-item-description>
    </ui-item-content>
    <ui-item-actions>
      <ui-button variant="outline" size="sm">Review</ui-button>
    </ui-item-actions>
  </ui-item>
</div>
```

### Image media

`variant="image"` crops an `<img>` into a rounded square.

```html live
<div class="demo-medium">
  <ui-item variant="outline">
    <ui-item-media variant="image">
      <img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' fill='%236366f1'/%3E%3Ccircle cx='44' cy='20' r='8' fill='%23e0e7ff'/%3E%3Cpath d='M0 64 22 30l18 22 10-12 14 24z' fill='%23c7d2fe'/%3E%3C/svg%3E" alt="">
    </ui-item-media>
    <ui-item-content>
      <ui-item-title>Midnight City Lights</ui-item-title>
      <ui-item-description>Neon Dreams</ui-item-description>
    </ui-item-content>
    <ui-item-actions>
      <span class="demo-muted">3:45</span>
    </ui-item-actions>
  </ui-item>
</div>
```

### With an avatar and several actions

Without `variant`, `ui-item-media` is a plain wrapper, so an avatar keeps its own look.

```html live
<div class="demo-medium">
  <ui-item variant="outline">
    <ui-item-media>
      <ui-avatar><ui-avatar-fallback>ER</ui-avatar-fallback></ui-avatar>
    </ui-item-media>
    <ui-item-content>
      <ui-item-title>Evil Rabbit</ui-item-title>
      <ui-item-description>Last seen 5 months ago</ui-item-description>
    </ui-item-content>
    <ui-item-actions>
      <ui-button variant="outline" size="sm">Message</ui-button>
      <ui-button size="sm">Invite</ui-button>
    </ui-item-actions>
  </ui-item>
</div>
```

### Extra content

`ui-item-content` is a flex column, so anything after the description stacks under it.

```html live
<div class="demo-medium">
  <ui-item variant="muted">
    <ui-item-content>
      <ui-item-title>Storage</ui-item-title>
      <ui-item-description>7.2 GB of 10 GB used</ui-item-description>
      <ui-progress value="72" aria-label="Storage used"></ui-progress>
    </ui-item-content>
  </ui-item>
</div>
```

### Header and footer

`ui-item-header` and `ui-item-footer` take a full row above or below the media, content and actions, with their
children spread apart.

```html live
<div class="demo-medium">
  <ui-item variant="outline">
    <ui-item-header>
      <span class="demo-muted">Deployment</span>
      <ui-badge variant="secondary">Ready</ui-badge>
    </ui-item-header>
    <ui-item-content>
      <ui-item-title>realm-site</ui-item-title>
      <ui-item-description>Production build from main, commit b6042d1.</ui-item-description>
    </ui-item-content>
    <ui-item-footer>
      <span class="demo-muted">2 minutes ago</span>
      <ui-button variant="ghost" size="sm">View logs</ui-button>
    </ui-item-footer>
  </ui-item>
</div>
```

### Group

`ui-item-group` stacks items. Put a `ui-separator` between them for a divided list.

```html live
<div class="demo-medium">
  <ui-item-group>
    <ui-item>
      <ui-item-media>
        <ui-avatar><ui-avatar-fallback>SC</ui-avatar-fallback></ui-avatar>
      </ui-item-media>
      <ui-item-content>
        <ui-item-title>realm</ui-item-title>
        <ui-item-description>realm@example.com</ui-item-description>
      </ui-item-content>
      <ui-item-actions>
        <ui-button variant="ghost" size="sm">Remove</ui-button>
      </ui-item-actions>
    </ui-item>
    <ui-separator></ui-separator>
    <ui-item>
      <ui-item-media>
        <ui-avatar><ui-avatar-fallback>ML</ui-avatar-fallback></ui-avatar>
      </ui-item-media>
      <ui-item-content>
        <ui-item-title>maxleiter</ui-item-title>
        <ui-item-description>maxleiter@vercel.com</ui-item-description>
      </ui-item-content>
      <ui-item-actions>
        <ui-button variant="ghost" size="sm">Remove</ui-button>
      </ui-item-actions>
    </ui-item>
  </ui-item-group>
</div>
```

### From state

Repeat items from a list with the `repeat` attribute, so each `ui-item` stays a direct child of the group and keeps
the `listitem` role.

```html live
<custom-element name="item-files-demo">
  <script type="realm">
    const folder = useState({
      files: [
        { id: "a", name: "invoice-march.pdf", size: "182 KB" },
        { id: "b", name: "team-photo.jpg", size: "2.4 MB" },
        { id: "c", name: "roadmap.md", size: "6 KB" },
      ],
    });

    function remove(file) {
      folder.files = folder.files.filter((item) => item.id !== file.id);
    }
  </script>
  <style type="realm">
    :host {
      display: block;
      width: min(100%, calc(var(--spacing) * 112));
    }
  </style>
  <ui-item-group>
    <ui-item size="sm" repeat="#folder.files" as="file" key="id">
      <ui-item-content>
        <ui-item-title><slot name="#file.name"></slot></ui-item-title>
        <ui-item-description><slot name="#file.size"></slot></ui-item-description>
      </ui-item-content>
      <ui-item-actions>
        <ui-button variant="ghost" size="sm" onclick="remove(file)">Delete</ui-button>
      </ui-item-actions>
    </ui-item>
  </ui-item-group>
</custom-element>
<item-files-demo></item-files-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-item` | | One row, laid out as a wrapping flex container with a gap. |
| `ui-item-group` | | A column of items with the role `list`. |
| `ui-item-media` | (default) | A non-shrinking box for an icon, image or avatar. Slotted `<svg>` is sized to `calc(var(--spacing) * 4)`. |
| `ui-item-content` | (default) | A flex column that fills the space between media and actions. |
| `ui-item-title` | (default) | The main line, in medium weight. Place it in `ui-item-content`. |
| `ui-item-description` | (default) | Secondary text in muted colour, clamped to two lines. Place it in `ui-item-content`. |
| `ui-item-actions` | (default) | A row of buttons or icons with a small gap. |
| `ui-item-header` | (default) | A full-width row above the rest, children spread apart. |
| `ui-item-footer` | (default) | A full-width row below the rest, children spread apart. |

`ui-item` lays its parts out in source order. Put media first, then content, then actions. Every part has a single
default slot that takes any content.

### ui-item attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default"` \| `"outline"` \| `"muted"` | `"default"` | Border and background style. |
| `size` | `"default"` \| `"sm"` | `"default"` | Padding and gap. |

### ui-item-media attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default"` \| `"icon"` \| `"image"` | `"default"` | `icon` is a `calc(var(--spacing) * 8)` bordered, muted box. `image` is a `calc(var(--spacing) * 10)` rounded box whose `<img>` covers it. `default` is a plain wrapper. |

The other parts have no attributes.

### Accessibility

`ui-item-group` has the role `list`, and a `ui-item` directly inside a group has the role `listitem`, so screen
readers report the list size. A standalone `ui-item` has no role. An item is not focusable or clickable by
itself. Put interactive elements in `ui-item-actions`, or wrap the item in an `<a>` to make the whole row a link.
Give an image in `ui-item-media` an `alt` text, or `alt=""` when the title already describes it.


---

# Kbd

Source: http://realm.js.org/components/kbd/

`ui-kbd` shows a single key or key label in a small muted box. `ui-kbd-group` puts several keys in a row for a
shortcut. Both are presentational. Wrap them in a native `<kbd>` when the text should be marked up as keyboard
input.

```html live
<ui-kbd-group>
  <ui-kbd>⌘</ui-kbd>
  <ui-kbd>⇧</ui-kbd>
  <ui-kbd>⌥</ui-kbd>
  <ui-kbd>⌃</ui-kbd>
</ui-kbd-group>
<ui-kbd-group>
  <ui-kbd>Ctrl</ui-kbd>
  <span>+</span>
  <ui-kbd>B</ui-kbd>
</ui-kbd-group>
```

## Examples

### In text

```html live
<p class="demo-muted">
  Press <ui-kbd>⌘</ui-kbd> <ui-kbd>K</ui-kbd> to open the command palette, or <ui-kbd>Esc</ui-kbd> to close it.
</p>
```

### In a button

A key label inside a button hints at its shortcut.

```html live
<ui-button variant="outline" size="sm">Search… <ui-kbd>⌘K</ui-kbd></ui-button>
<ui-button variant="outline" size="sm">Accept <ui-kbd>⏎</ui-kbd></ui-button>
```

### With semantic markup

Wrap the keys in `<kbd>` so the shortcut is also marked up as keyboard input. Each `ui-kbd` sets its own font, so
the native monospace font of `<kbd>` does not reach the key labels.

```html live
<kbd>
  <ui-kbd-group>
    <ui-kbd>Ctrl</ui-kbd>
    <ui-kbd>Shift</ui-kbd>
    <ui-kbd>P</ui-kbd>
  </ui-kbd-group>
</kbd>
```

### In a tooltip

```html live
<ui-tooltip>
  <ui-tooltip-trigger><ui-button variant="outline">Save</ui-button></ui-tooltip-trigger>
  <ui-tooltip-content>Save draft <ui-kbd>⌘S</ui-kbd></ui-tooltip-content>
</ui-tooltip>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-kbd` | (default) | One key in a small muted box. Its default slot takes the key label: a character, a word, or a small `<svg>` icon. |
| `ui-kbd-group` | (default) | An inline row of keys with a small gap. Its default slot takes the `ui-kbd` elements and any separators such as `+` or `then`. |

### Attributes

Neither element has attributes.

### CSS parts

None. Both elements render only a slot.

### Accessibility

Neither element has a role. Screen readers read the key labels as text, so prefer words such as `Ctrl` or
`Esc` over symbols when the audience may not know the symbols, or add visually hidden text. `ui-kbd` sets
`pointer-events: none` and `user-select: none`, so clicks go to the surrounding element.


---

# Progress

Source: http://realm.js.org/components/progress/

`ui-progress` renders a native `<progress>` element styled as a thin rounded bar. Set `value`, and optionally
`max`, to show how much of a task is done. The bar is as wide as its container, so size it with a wrapper.

```html live
<div class="demo-narrow">
  <ui-progress value="60" aria-label="Progress"></ui-progress>
</div>
```

## Examples

### Custom maximum

`max` defaults to `100`. Set it to the total so `value` can be a plain count.

```html live
<div class="demo-narrow demo-stack-tight">
  <p class="demo-text">3 of 8 steps</p>
  <ui-progress value="3" max="8" aria-label="Steps completed"></ui-progress>
</div>
```

### With a label

Show the task name and percentage as text next to the bar.

```html live
<div class="demo-narrow demo-stack-tight">
  <div class="demo-row-tight">
    <p class="demo-text">Uploading report.pdf</p>
    <p class="demo-muted">45%</p>
  </div>
  <ui-progress value="45" aria-label="Uploading report.pdf"></ui-progress>
</div>
```

### Driven by state

Bind `value` with `_value`. The bar animates between values.

```html live
<custom-element name="progress-upload-demo">
  <script type="realm">
    const upload = useState({ percent: 13 });

    function advance() {
      upload.percent = upload.percent >= 100 ? 0 : Math.min(100, upload.percent + 22);
    }
  </script>
  <style type="realm">
    :host {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 4);
      width: 70%;
    }
    ui-progress {
      flex: 1;
    }
    span {
      min-width: calc(var(--spacing) * 10);
      font-size: var(--text-sm);
      font-variant-numeric: tabular-nums;
    }
  </style>
  <ui-progress _value="#upload.percent"></ui-progress>
  <span><slot name="#upload.percent"></slot>%</span>
  <ui-button size="sm" variant="outline" onclick="advance()">Advance</ui-button>
</custom-element>
<progress-upload-demo></progress-upload-demo>
```

### Custom colour

The bar uses `var(--primary)`. Set `--primary` on a wrapping element to recolour the bar and its track.

```html live
<div class="demo-narrow demo-stack">
  <div style="--primary: var(--chart-2)">
    <ui-progress value="80" aria-label="Storage used"></ui-progress>
  </div>
  <div style="--primary: var(--destructive)">
    <ui-progress value="30" aria-label="Battery"></ui-progress>
  </div>
</div>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | number | none | Current value, minimum `0`. When it is left out the bar is indeterminate. |
| `max` | number | `100` | Value that means complete, minimum `1`. |
| `aria-label` | string | | Accessible name, passed to the inner `<progress>`. Property name: `label`. |

### Parts

`ui-progress` has no child parts. Its default slot takes fallback text inside the native `<progress>`, for example
`45%`, which browsers that support `<progress>` do not render.

### CSS parts

| Part | Description |
| --- | --- |
| `bar` | The native `<progress>` element. Its height is `calc(var(--spacing) * 2)`. |

### Accessibility

The inner `<progress>` has the native `progressbar` role, with its value and maximum exposed to assistive
technology. Name it with `aria-label` on `ui-progress`, which is passed to the inner bar. A `<label for>` outside
cannot reach into the shadow root. Without `value` the bar is indeterminate and exposes no value.


---

# Separator

Source: http://realm.js.org/components/separator/

`ui-separator` draws a one pixel line in the border colour. It is horizontal by default and fills the width of
its container. Set `orientation="vertical"` to divide items in a row. The element has the role `separator` and
reports its orientation to assistive technology. It has no margin. The space around it comes from the gap of its
container.

```html live
<div class="demo-narrow demo-stack demo-text">
  <div class="demo-stack-tight">
    <strong>REALM UI</strong>
    <p class="demo-muted">Native custom elements for every app.</p>
  </div>
  <ui-separator></ui-separator>
  <div class="demo-row">
    <span>Blog</span>
    <ui-separator orientation="vertical"></ui-separator>
    <span>Docs</span>
    <ui-separator orientation="vertical"></ui-separator>
    <span>Source</span>
  </div>
</div>
```

## Examples

### Vertical

A vertical separator stretches to the height of its flex row, which the tallest item sets.

```html live
<div class="demo-row-tight">
  <ui-button variant="ghost" size="sm">Bold</ui-button>
  <ui-button variant="ghost" size="sm">Italic</ui-button>
  <ui-separator orientation="vertical"></ui-separator>
  <ui-button variant="ghost" size="sm">Link</ui-button>
</div>
```

### Between list items

```html live
<div class="demo-narrow demo-stack-tight demo-text">
  <div>Account</div>
  <ui-separator></ui-separator>
  <div>Billing</div>
  <ui-separator></ui-separator>
  <div>Notifications</div>
</div>
```

### With a label

For a label between two lines, such as an "or" divider, use `<ui-marker variant="separator">` instead of two
separators.

```html live
<div class="demo-narrow">
  <ui-marker variant="separator">Or continue with</ui-marker>
</div>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-separator` | (default) | A one pixel line in `var(--border)`, 100% wide when horizontal. It has no slot and takes no content. |

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal"` \| `"vertical"` | `"horizontal"` | Direction of the line. Also sets `aria-orientation`. |

### CSS parts

None. The separator renders no shadow content. Style the element itself.

### Accessibility

The element has the role `separator` and `aria-orientation` set from `orientation`, both through
`ElementInternals`. For a decorative line that should be skipped by screen readers, add
`role="none"`.


---

# Skeleton

Source: http://realm.js.org/components/skeleton/

`ui-skeleton` is an empty block with a muted background and a slow pulse. Size it with `width` and `height` in
spacing units (`width="12"` is `calc(var(--spacing) * 12)`), and set `shape="circle"` for avatars. Without a
`width` it fills its container. The pulse stops when the user prefers reduced motion.

```html live
<div class="demo-row">
  <ui-skeleton shape="circle" width="12" height="12"></ui-skeleton>
  <div class="demo-stack-tight">
    <ui-skeleton width="62" height="4"></ui-skeleton>
    <ui-skeleton width="50" height="4"></ui-skeleton>
  </div>
</div>
```

## Examples

### Card

Skeletons without a `width` fill the wrapper, so the wrapper sets the width of the whole placeholder.

```html live
<div class="demo-narrow demo-stack">
  <ui-skeleton height="32"></ui-skeleton>
  <div class="demo-stack-tight">
    <ui-skeleton height="4"></ui-skeleton>
    <ui-skeleton width="50" height="4"></ui-skeleton>
  </div>
</div>
```

### While loading

Show skeletons until data arrives, then swap them for the content with `<is-visible>` and `<is-hidden>`.

```html live
<custom-element name="skeleton-profile-demo">
  <script type="realm">
    const profile = useState({ loaded: false });

    function toggle() {
      profile.loaded = !profile.loaded;
    }
  </script>
  <style type="realm">
    :host {
      display: grid;
      justify-items: start;
      gap: calc(var(--spacing) * 4);
      width: calc(var(--spacing) * 72);
    }
    .row {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 3);
      height: calc(var(--spacing) * 10);
      font-size: var(--text-sm);
    }
    .lines {
      display: grid;
      gap: calc(var(--spacing) * 2);
    }
    small {
      color: var(--muted-foreground);
    }
  </style>
  <is-hidden when="#profile.loaded">
    <div class="row" aria-busy="true">
      <ui-skeleton shape="circle" width="8" height="8"></ui-skeleton>
      <div class="lines"><ui-skeleton width="40" height="3"></ui-skeleton><ui-skeleton width="40" height="3"></ui-skeleton></div>
    </div>
  </is-hidden>
  <is-visible when="#profile.loaded">
    <div class="row">
      <ui-avatar><ui-avatar-fallback>OM</ui-avatar-fallback></ui-avatar>
      <div class="lines"><span>Olivia Martin</span><small>olivia.martin@email.com</small></div>
    </div>
  </is-visible>
  <ui-button size="sm" variant="outline" onclick="toggle()">Toggle loaded</ui-button>
</custom-element>
<skeleton-profile-demo></skeleton-profile-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-skeleton` | (default) | A pulsing block in `var(--accent)` with `var(--radius-md)` corners. It has no slot and takes no content. |

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | number | none | Width in spacing units (`calc(var(--spacing) * width)`). Without it the skeleton fills its container. |
| `height` | number | none | Height in spacing units. |
| `shape` | `"circle"` | none | Fully rounded corners, and the skeleton does not shrink in a flex row. Use with equal `width` and `height`. |

### CSS parts

None. The skeleton renders no shadow content.

### Accessibility

The skeleton has no role and no text, so screen readers ignore it. Mark the loading region with
`aria-busy="true"` and remove it when the content is in place.


---

# Spinner

Source: http://realm.js.org/components/spinner/

`ui-spinner` is a small rotating arc that shows work in progress. It has the role `status` and an accessible
name taken from `label`, which defaults to "Loading". By default it inherits the current text colour. `variant`
picks a theme colour instead.

```html live
<ui-spinner></ui-spinner>
```

## Examples

### Sizes

`size` is the width and height in pixels, at least `8`.

```html live
<ui-spinner size="12"></ui-spinner>
<ui-spinner size="16"></ui-spinner>
<ui-spinner size="24"></ui-spinner>
<ui-spinner size="32"></ui-spinner>
```

### Colour

`variant` sets the colour of the arc. The `default` variant uses `currentColor`, so it matches the surrounding
text.

```html live
<ui-spinner size="24"></ui-spinner>
<ui-spinner size="24" variant="primary"></ui-spinner>
<ui-spinner size="24" variant="muted"></ui-spinner>
<ui-spinner size="24" variant="destructive"></ui-spinner>
```

### In a button

Show a spinner inside a disabled button while a request runs.

```html live
<custom-element name="spinner-button-demo">
  <script type="realm">
    const request = useState({ busy: false });

    function save() {
      request.busy = true;
      const timer = setTimeout(() => {
        request.busy = false;
      }, 1500);
      signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
    }
  </script>
  <ui-button _disabled="#request.busy" onclick="save()">
    <is-visible when="#request.busy"><ui-spinner size="14" label="Saving"></ui-spinner></is-visible>
    Save changes
  </ui-button>
</custom-element>
<spinner-button-demo></spinner-button-demo>
```

### With a badge

```html live
<ui-badge variant="secondary"><ui-spinner size="12" label="Syncing"></ui-spinner> Syncing</ui-badge>
<ui-badge variant="outline"><ui-spinner size="12" label="Processing"></ui-spinner> Processing</ui-badge>
```

### Custom label

Change `label` to describe the work. It becomes the spinner's accessible name.

```html live
<div class="demo-row-tight demo-muted">
  <ui-spinner label="Loading messages"></ui-spinner>
  Loading messages…
</div>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-spinner` | (default) | A rotating arc drawn with an inline `<svg>`. It has no slot and takes no content. |

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | number | `16` | Width and height in pixels. Minimum `8`. |
| `label` | string | `"Loading"` | Accessible name of the spinner. |
| `variant` | `"default"` \| `"primary"` \| `"muted"` \| `"destructive"` | `"default"` | Colour of the arc. `default` uses `currentColor`. |

### CSS parts

None. Set `color` on the element to use a colour outside the variants.

### Accessibility

The element has the role `status` and its `aria-label` comes from `label`, both through `ElementInternals`. The
SVG is hidden from assistive technology. With reduced motion preferred, the rotation slows to a third of its
normal speed instead of stopping, so the indicator still shows that something is happening.


---

# Table

Source: http://realm.js.org/components/table/

`ui-table` renders a native `<table>` from two properties: `columns`, which lists the keys and header labels, and
`rows`, a list of plain objects. Each cell shows the row's value for the column key as text. The table fills the
width of its container and scrolls horizontally when its content is wider.

```html live
<ui-table
  caption="A list of your recent invoices."
  columns='[{"key":"invoice","label":"Invoice"},{"key":"status","label":"Status"},{"key":"method","label":"Method"},{"key":"amount","label":"Amount"}]'
  rows='[{"id":"INV001","invoice":"INV001","status":"Paid","method":"Credit card","amount":"$250.00"},{"id":"INV002","invoice":"INV002","status":"Pending","method":"PayPal","amount":"$150.00"},{"id":"INV003","invoice":"INV003","status":"Unpaid","method":"Bank transfer","amount":"$350.00"}]'>
</ui-table>
```

## Examples

### Data from component state

In a component, bind `columns` and `rows` with `_columns` and `_rows`. Arrays and objects are passed as properties,
so the table re-renders whenever the state changes. Here the rows are a getter that filters and sorts the data.

```html live
<custom-element name="table-invoices-demo">
  <script type="realm">
    const COLUMNS = [
      { key: "id", label: "Invoice" },
      { key: "customer", label: "Customer" },
      { key: "status", label: "Status" },
      { key: "total", label: "Amount" },
    ];
    const INVOICES = [
      { id: "INV001", customer: "Olivia Martin", status: "Paid", amount: 250 },
      { id: "INV002", customer: "Jackson Lee", status: "Pending", amount: 150 },
      { id: "INV003", customer: "Isabella Nguyen", status: "Unpaid", amount: 350 },
      { id: "INV004", customer: "William Kim", status: "Paid", amount: 450 },
      { id: "INV005", customer: "Sofia Davis", status: "Paid", amount: 550 },
    ];
    const currency = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });

    const invoices = useState({
      columns: COLUMNS,
      paidOnly: false,
      get rows() {
        return INVOICES.filter((invoice) => !this.paidOnly || invoice.status === "Paid")
          .toSorted((a, b) => b.amount - a.amount)
          .map((invoice) => ({ ...invoice, total: currency.format(invoice.amount) }));
      },
    });

    function filter(event) {
      invoices.paidOnly = event.target.checked;
    }
  </script>
  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      width: 100%;
    }
    label {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 2);
      font-size: var(--text-sm);
    }
  </style>
  <label><input type="checkbox" onchange="filter(event)"> Paid only</label>
  <ui-table _columns="#invoices.columns" _rows="#invoices.rows" caption="Sorted by amount, highest first."></ui-table>
</custom-element>
<table-invoices-demo></table-invoices-demo>
```

### Column labels

`label` is optional. Without it, the header shows the column `key`.

```html live
<ui-table
  columns='[{"key":"name"},{"key":"role"},{"key":"email","label":"Email address"}]'
  rows='[{"id":1,"name":"Ada","role":"Owner","email":"ada@example.com"},{"id":2,"name":"Linus","role":"Member","email":"linus@example.com"}]'>
</ui-table>
```

### Custom cells with a native table

`ui-table` cells hold text only. When cells need badges, buttons or links, write a native `<table>` in your
component and repeat the rows with the `repeat` attribute on `<tr>` (inside `<table>`, `<ul>`, `<ol>` and
`<select>`, use `repeat` on the item rather than `<repeat-list>`, so the HTML parser keeps the structure).

```html live
<custom-element name="table-members-demo">
  <script type="realm">
    const ROLE_VARIANTS = { Owner: "default", Admin: "secondary", Member: "outline" };

    const team = useState({
      members: [
        { id: 1, name: "Olivia Martin", email: "olivia@example.com", role: "Owner" },
        { id: 2, name: "Jackson Lee", email: "jackson@example.com", role: "Admin" },
        { id: 3, name: "Sofia Davis", email: "sofia@example.com", role: "Member" },
      ],
      get rows() {
        return this.members.map((member) => ({
          ...member,
          variant: ROLE_VARIANTS[member.role],
          initials: member.name.split(" ").map((part) => part[0]).join(""),
        }));
      },
    });

    function remove(member) {
      team.members = team.members.filter((item) => item.id !== member.id);
    }
  </script>
  <style type="realm">
    :host {
      display: block;
      width: 100%;
      overflow-x: auto;
    }
    table {
      width: 100%;
      border-collapse: collapse;
      font-size: var(--text-sm);
    }
    th {
      height: calc(var(--spacing) * 10);
      padding: 0 calc(var(--spacing) * 2);
      text-align: left;
      font-weight: var(--font-weight-medium);
    }
    td {
      padding: calc(var(--spacing) * 2);
    }
    tr {
      border-bottom: 1px solid var(--border);
    }
    tbody tr:last-child {
      border-bottom: 0;
    }
    .person {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 3);
    }
    small {
      display: block;
      color: var(--muted-foreground);
    }
    .actions {
      text-align: right;
    }
  </style>
  <table>
    <thead>
      <tr><th>Member</th><th>Role</th><th class="actions">Actions</th></tr>
    </thead>
    <tbody>
      <tr repeat="#team.rows" as="member" key="id">
        <td>
          <div class="person">
            <ui-avatar><ui-avatar-fallback><slot name="#member.initials"></slot></ui-avatar-fallback></ui-avatar>
            <div><slot name="#member.name"></slot><small><slot name="#member.email"></slot></small></div>
          </div>
        </td>
        <td><ui-badge _variant="#member.variant"><slot name="#member.role"></slot></ui-badge></td>
        <td class="actions"><ui-button size="sm" variant="ghost" onclick="remove(member)">Remove</ui-button></td>
      </tr>
    </tbody>
  </table>
</custom-element>
<table-members-demo></table-members-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | array of `{ key: string, label?: string }` | `[]` | The columns, in order. `key` is required and selects the value from each row. `label` is the header text and falls back to `key`. Accepts JSON in the attribute, or an array through the `columns` property or a `_columns` binding. |
| `rows` | array of objects | `[]` | The rows. Each object's values are looked up by column key. Missing values render as empty cells. A row's `id`, when present, keys the row so updates reuse its DOM. Otherwise the index is used. Accepts JSON or an array, like `columns`. |
| `caption` | string | none | Text for the table's `<caption>`, shown under the table. The caption is hidden when this is not set. |

### Properties

`columns` and `rows` are also properties. Assigning a new array re-renders the table:

```html
<ui-table id="people"></ui-table>
<script>
  const table = document.getElementById("people");
  table.columns = [{ key: "name", label: "Name" }, { key: "email", label: "Email" }];
  table.rows = [{ id: 1, name: "Ada", email: "ada@example.com" }];
</script>
```

### Parts

`ui-table` has no child parts and no slots. It renders everything from `columns`, `rows` and `caption`. For cells
with markup, use a native table as shown above.

### CSS parts

| Part | Description |
| --- | --- |
| `table` | The native `<table>`. |
| `head` | Each header cell (`<th>`). |
| `row` | Each body row (`<tr>`). |
| `cell` | Each body cell (`<td>`). |

Rows get a bottom border and a muted background on hover. Cells do not wrap. Long tables scroll horizontally
inside the element.

### Accessibility

The output is a native `<table>` with `<thead>`, `<th>` header cells and an optional `<caption>`, so screen
readers announce row and column headers. Set `caption` to give the table a name.


---

# Alert Dialog

Source: http://realm.js.org/components/alert-dialog/

`ui-alert-dialog` is a modal `<dialog>` with `role="alertdialog"` for confirmations that need an answer, such as
deleting data. Escape does nothing, and there is no close button or backdrop dismissal. The dialog closes when the user
picks `ui-alert-dialog-cancel` or `ui-alert-dialog-action`. Each stores its `value` in `returnValue`.

`ui-alert-dialog-trigger` opens the dialog. The header holds the title and description, and the footer holds the actions.

```html live
<ui-alert-dialog>
  <ui-alert-dialog-trigger><ui-button variant="outline">Delete account</ui-button></ui-alert-dialog-trigger>
  <ui-alert-dialog-header>
    <ui-alert-dialog-title>Are you absolutely sure?</ui-alert-dialog-title>
    <ui-alert-dialog-description>This permanently deletes your account and removes your data from our servers.</ui-alert-dialog-description>
  </ui-alert-dialog-header>
  <ui-alert-dialog-footer>
    <ui-alert-dialog-cancel>Cancel</ui-alert-dialog-cancel>
    <ui-alert-dialog-action value="delete" variant="destructive">Delete account</ui-alert-dialog-action>
  </ui-alert-dialog-footer>
</ui-alert-dialog>
```

## Examples

### Read the chosen action

The `close` event fires after the dialog closes. Read `returnValue` to find out which action was chosen.
`ui-alert-dialog-cancel` stores `"cancel"` and `ui-alert-dialog-action` stores `"action"` unless you set `value`.

```html live
<custom-element name="alert-dialog-result-demo">
  <script type="realm">
    const project = useState({ status: "Project \"Atlas\" is active." });

    const RESULTS = {
      archive: "Project \"Atlas\" was archived.",
      cancel: "Nothing changed.",
    };

    function closed() {
      project.status = RESULTS[refs.alert.returnValue] ?? project.status;
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 4);
      font-size: var(--text-sm);
    }
  </style>

  <ui-alert-dialog ref="alert" onclose="closed()">
    <ui-alert-dialog-trigger><ui-button variant="outline">Archive project</ui-button></ui-alert-dialog-trigger>
    <ui-alert-dialog-header>
      <ui-alert-dialog-title>Archive this project?</ui-alert-dialog-title>
      <ui-alert-dialog-description>Archived projects are read-only. You can restore them from settings.</ui-alert-dialog-description>
    </ui-alert-dialog-header>
    <ui-alert-dialog-footer>
      <ui-alert-dialog-cancel>Cancel</ui-alert-dialog-cancel>
      <ui-alert-dialog-action value="archive">Archive</ui-alert-dialog-action>
    </ui-alert-dialog-footer>
  </ui-alert-dialog>
  <span><slot name="#project.status"></slot></span>
</custom-element>
<alert-dialog-result-demo></alert-dialog-result-demo>
```

### Open with a command

A button outside the dialog can open it with `commandfor` and `command="--show-modal"`. The `--close` command closes
it without changing `returnValue`.

```html live
<ui-button variant="outline" commandfor="alert-dialog-session" command="--show-modal">Sign out</ui-button>
<ui-alert-dialog id="alert-dialog-session">
  <ui-alert-dialog-header>
    <ui-alert-dialog-title>Your session will end</ui-alert-dialog-title>
    <ui-alert-dialog-description>Unsaved changes in open tabs will be lost.</ui-alert-dialog-description>
  </ui-alert-dialog-header>
  <ui-alert-dialog-footer>
    <ui-alert-dialog-cancel>Stay signed in</ui-alert-dialog-cancel>
    <ui-alert-dialog-action value="sign-out">Sign out</ui-alert-dialog-action>
  </ui-alert-dialog-footer>
</ui-alert-dialog>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-alert-dialog` | | The modal `<dialog>` with `role="alertdialog"`, a grid with a gap between the header, content and footer. |
| `ui-alert-dialog-trigger` | `trigger` | Its content, outside the dialog. A click on it focuses the element inside and opens the dialog. |
| `ui-alert-dialog-header` | `header` | A column for the title and description. |
| `ui-alert-dialog-title` | (default) | An `<h2>` in `var(--text-lg)` semibold. Its text becomes the dialog's accessible name. |
| `ui-alert-dialog-description` | (default) | A `<p>` in muted `var(--text-sm)`. Its text becomes the dialog's accessible description. |
| `ui-alert-dialog-footer` | `footer` | A row of actions, aligned to the end and wrapped on narrow screens. |
| `ui-alert-dialog-cancel` | (default) | An outline `ui-button`. Closes the dialog with its `value`. |
| `ui-alert-dialog-action` | (default) | A `ui-button` in the chosen `variant`. Closes the dialog with its `value`. |

Parts with a slot assign themselves to it, so you do not write `slot`. Other content goes between the header and the
footer.

### ui-alert-dialog attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | boolean | `false` | Whether the dialog is open. Setting it opens the dialog modally. Reflects. |

### ui-alert-dialog-action attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `"action"` | Stored in `returnValue` when the action closes the dialog. |
| `variant` | `"default"` \| `"destructive"` | `"default"` | The button variant. |

### ui-alert-dialog-cancel attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `"cancel"` | Stored in `returnValue` when the cancel button closes the dialog. |

### Properties and methods

| Name | Description |
| --- | --- |
| `showModal()` | Opens the dialog modally. |
| `show()` | Same as `showModal()`. |
| `close(value?)` | Closes the dialog. When `value` is given it becomes `returnValue`. |
| `returnValue` | Read-only. The `value` of the chosen action or cancel part, or the value passed to `close(value)`. |
| `open` | Boolean property mirroring the attribute. |

### Commands

| Command | Action |
| --- | --- |
| `--show-modal` | Opens the dialog. |
| `--close` | Closes the dialog. |
| `--request-close` | Same as `--close`, because the alert dialog has no cancel step. |

`ui-button` also accepts the commands without the `--` prefix. A plain `<button>` needs the prefix.

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `close` | none | Fired after the dialog has closed. Does not bubble. |

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-alert-dialog` | `dialog` | The native `<dialog>` element. |
| `ui-alert-dialog-title` | `title` | The `<h2>`. |
| `ui-alert-dialog-description` | `description` | The `<p>`. |
| `ui-alert-dialog-action`, `ui-alert-dialog-cancel` | `button` | The inner `ui-button`. |
| `ui-alert-dialog-trigger` | `trigger` | The wrapper that listens for clicks. |

### Accessibility

- The inner `<dialog>` has `role="alertdialog"` and is opened with `showModal()`, so the page behind it is inert.
- The text of the title and description parts becomes the dialog's `aria-label` and `aria-description`.
- On open, focus moves to the first action. Put the safe choice (Cancel) first.
- Escape is ignored and there is no backdrop dismissal, so the user must make a choice.
- On close, focus returns to the trigger.


---

# Command

Source: http://realm.js.org/components/command/

`ui-command` is a search box above a filtered list of options. The options come from plain `<option>` children, and
native `<optgroup label="…">` elements group them under a heading. Type to filter by label or value, use the arrow
keys to move the highlight and press Enter, or click an option, to fire a `select` event. `data-shortcut` on an
option shows a shortcut hint, and `ui-command-empty` sets what shows when nothing matches.

`ui-command` fills the width of its container. On its own it renders inline. Put it in a [Dialog](/components/dialog/)
to make a command palette. The search on this site works that way.

```html live
<div class="demo-narrow">
  <ui-command onselect="document.dispatchEvent(new CustomEvent('toast', { detail: { title: event.detail.label } }))">
    <optgroup label="Suggestions">
      <option value="calendar">Calendar</option>
      <option value="emoji">Search emoji</option>
      <option value="calculator">Calculator</option>
    </optgroup>
    <optgroup label="Settings">
      <option value="profile" data-shortcut="⌘P">Profile</option>
      <option value="billing" data-shortcut="⌘B">Billing</option>
      <option value="settings" data-shortcut="⌘S">Settings</option>
    </optgroup>
  </ui-command>
</div>
```

## Examples

### Command palette in a dialog

Put `ui-command` in a `ui-dialog` with `hide-close`, open the dialog with `showModal()` and close it from the `select`
handler. Focus the search input after opening so the user can type straight away.

```html live
<custom-element name="command-palette-demo">
  <script type="realm">
    function open() {
      refs.palette.showModal();
      refs.command.shadowRoot.querySelector("input").focus();
    }

    function run(event) {
      refs.palette.close();
      document.dispatchEvent(new CustomEvent("toast", { detail: { title: `Running "${event.detail.label}"` } }));
    }
  </script>

  <style type="realm">
    ui-command {
      margin: calc(var(--spacing) * -6);
      border: 0;
    }
  </style>

  <ui-button variant="outline" onclick="open()">Open command palette</ui-button>
  <ui-dialog ref="palette" label="Command palette" hide-close>
    <ui-command ref="command" placeholder="Type a command..." onselect="run(event)">
      <optgroup label="File">
        <option value="new-file" data-shortcut="⌘N">New file</option>
        <option value="open-file" data-shortcut="⌘O">Open file</option>
      </optgroup>
      <optgroup label="View">
        <option value="toggle-theme">Toggle theme</option>
        <option value="zoom-in" data-shortcut="⌘+">Zoom in</option>
      </optgroup>
    </ui-command>
  </ui-dialog>
</custom-element>
<command-palette-demo></command-palette-demo>
```

### Options from state

Generate the groups and options with `repeat`. `ui-command` watches its children, so the list updates when the state
changes. `value` falls back to the option text, and the `label` attribute overrides the text.

```html live
<custom-element name="command-state-demo">
  <script type="realm">
    const people = useState({
      teams: [
        {
          name: "Engineering",
          members: [
            { id: "ada", name: "Ada Lovelace" },
            { id: "grace", name: "Grace Hopper" },
          ],
        },
        { name: "Research", members: [{ id: "katherine", name: "Katherine Johnson" }] },
      ],
      picked: "nobody",
    });

    function pick(event) {
      people.picked = event.detail.label;
    }

    function add() {
      people.teams[1].members.push({ id: "margaret", name: "Margaret Hamilton" });
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      width: min(100%, calc(var(--spacing) * 112));
      font-size: var(--text-sm);
    }
    .row {
      display: flex;
      align-items: center;
      justify-content: space-between;
    }
  </style>

  <ui-command placeholder="Find a person..." onselect="pick(event)">
    <optgroup repeat="#people.teams" as="team" key="name" _label="#team.name">
      <option repeat="#team.members" as="person" key="id" _value="#person.id" _label="#person.name"></option>
    </optgroup>
    <ui-command-empty>Nobody matches.</ui-command-empty>
  </ui-command>
  <div class="row">
    <span>Picked: <slot name="#people.picked"></slot></span>
    <ui-button size="sm" variant="secondary" onclick="add()">Add Margaret</ui-button>
  </div>
</custom-element>
<command-state-demo></command-state-demo>
```

### Empty state

`ui-command-empty` replaces the default "No results found." text, and can hold markup. Type something that is not in
the list to see it.

```html live
<div class="demo-narrow">
  <ui-command placeholder="Search frameworks...">
    <option value="realm">REALM</option>
    <option value="lit">Lit</option>
    <option value="stencil">Stencil</option>
    <ui-command-empty>No framework found. <a href="#command">Suggest one</a></ui-command-empty>
  </ui-command>
</div>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-command` | | A bordered column with the search input above the filtered list. Fills its container's width. |
| `<optgroup label="…">` | (data) | A group with the label as its heading. Groups after the first are separated by a line. |
| `<option>` | (data) | One row in the list, with the `data-shortcut` hint at the end. |
| `ui-command-empty` | `empty` | The text shown when nothing matches, in place of "No results found.". |

`<option>` and `<optgroup>` are hidden and used only as data. Changing them updates the list. Options
outside a group are listed without a heading.

### ui-command attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholder` | string | `"Type a command or search..."` | Placeholder of the search input. |

### Option attributes

| Attribute | Description |
| --- | --- |
| `value` | Sent in `event.detail.value`. Also matched by the search. Defaults to the option text. |
| `label` | Text shown in the list and matched by the search. Defaults to the option text. |
| `data-shortcut` | Shortcut hint shown at the end of the row. Display only. It does not bind a key. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `select` | `{ value, label }` | Fired when an option is clicked or Enter is pressed on the highlighted option. Bubbles and is composed. |

### CSS parts

| Part | Description |
| --- | --- |
| `search` | The row with the search icon and input. |
| `input` | The search `<input>`. |
| `list` | The scrolling list (`role="listbox"`). |
| `item` | Each option row (`role="option"`). |
| `shortcut` | The shortcut hint in a row. |
| `empty` | The paragraph shown when nothing matches. |

### Accessibility

- The search input has `role="combobox"`, `aria-expanded="true"` and `aria-autocomplete="list"`. The list has
  `role="listbox"`, groups have `role="group"`, and each row has `role="option"` with `aria-selected` on the
  highlighted one.
- Arrow Down and Arrow Up move the highlight and wrap around. Enter selects the highlighted option. Typing resets the
  highlight to the first match.
- Focus stays in the input while navigating. The input's `aria-activedescendant` points at the highlighted option
  and `aria-controls` at the listbox. The rows are rendered in the same shadow root as the input so these references
  work. This is why options are data and not separate item elements.


---

# Context Menu

Source: http://realm.js.org/components/context-menu/

`ui-context-menu` replaces the browser's context menu inside `ui-context-menu-trigger`. A right-click (or the context
menu key) on the trigger opens `ui-context-menu-content`, a `popover="auto"` menu, at the pointer position and
focuses the first enabled item. The items are the same `ui-menu-*` parts used by
[Dropdown Menu](/components/dropdown-menu/). The arrow keys move between them, Enter or Space chooses one, and choosing
fires `select` and closes the menu. Escape and a click outside close it too.

```html live
<ui-context-menu onselect="document.dispatchEvent(new CustomEvent('toast', { detail: { title: 'Chose ' + event.detail.value } }))">
  <ui-context-menu-trigger><div class="demo-area">Right click here</div></ui-context-menu-trigger>
  <ui-context-menu-content>
    <ui-menu-item value="back">Back <ui-menu-shortcut>⌘[</ui-menu-shortcut></ui-menu-item>
    <ui-menu-item value="forward" disabled>Forward <ui-menu-shortcut>⌘]</ui-menu-shortcut></ui-menu-item>
    <ui-menu-item value="reload">Reload <ui-menu-shortcut>⌘R</ui-menu-shortcut></ui-menu-item>
    <ui-menu-separator></ui-menu-separator>
    <ui-menu-checkbox-item value="bookmarks" checked>Show Bookmarks</ui-menu-checkbox-item>
    <ui-menu-separator></ui-menu-separator>
    <ui-menu-label>People</ui-menu-label>
    <ui-menu-radio-group value="pedro">
      <ui-menu-radio-item value="pedro">Pedro Duarte</ui-menu-radio-item>
      <ui-menu-radio-item value="colm">Colm Tuite</ui-menu-radio-item>
    </ui-menu-radio-group>
  </ui-context-menu-content>
</ui-context-menu>
```

## Examples

### Handle the selection

`select` bubbles from the chosen item, and `event.detail.value` is its `value`.

```html live
<custom-element name="context-menu-file-demo">
  <script type="realm">
    const file = useState({ name: "report.pdf", log: "Right click the file." });

    const ACTIONS = {
      open: (name) => `Opened ${name}.`,
      rename: (name) => `Renaming ${name}.`,
      delete: (name) => `Deleted ${name}.`,
    };

    function act(event) {
      file.log = ACTIONS[event.detail.value](file.name);
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      justify-items: center;
      gap: calc(var(--spacing) * 3);
      font-size: var(--text-sm);
    }
    .file {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 2);
      padding: calc(var(--spacing) * 3) calc(var(--spacing) * 4);
      border: 1px solid var(--border);
      border-radius: var(--radius-md);
    }
    svg {
      width: calc(var(--spacing) * 4);
      height: calc(var(--spacing) * 4);
    }
    output {
      color: var(--muted-foreground);
    }
  </style>

  <ui-context-menu onselect="act(event)">
    <ui-context-menu-trigger>
      <div class="file">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M14 3H6v18h12V7Z" /><path d="M14 3v4h4" /></svg>
        <slot name="#file.name"></slot>
      </div>
    </ui-context-menu-trigger>
    <ui-context-menu-content>
      <ui-menu-item value="open">Open</ui-menu-item>
      <ui-menu-item value="rename">Rename</ui-menu-item>
      <ui-menu-separator></ui-menu-separator>
      <ui-menu-item value="delete" variant="destructive">Delete</ui-menu-item>
    </ui-context-menu-content>
  </ui-context-menu>
  <output><slot name="#file.log"></slot></output>
</custom-element>
<context-menu-file-demo></context-menu-file-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-context-menu` | | Its parts, with no box of its own. |
| `ui-context-menu-trigger` | (default) | A block around the area. A `contextmenu` event inside it opens the menu at the pointer. |
| `ui-context-menu-content` | (default) | A bordered `popover="auto"` panel with `role="menu"`, positioned at the pointer with `position: fixed`. |
| `ui-menu-*` | (default) | Items, labels, groups, separators and shortcuts. See [Dropdown Menu](/components/dropdown-menu/). |

None of the parts has attributes of its own. See [Dropdown Menu](/components/dropdown-menu/) for the item attributes
(`value`, `disabled`, `variant`, `checked`).

### Events

| Event | Element | Detail | Description |
| --- | --- | --- | --- |
| `select` | `ui-menu-item`, `ui-menu-radio-item` | `{ value }` | Fired when an enabled item is chosen. Bubbles to `ui-context-menu`. The menu closes afterwards. |
| `select` | `ui-menu-checkbox-item` | `{ value, checked }` | Same, with the new checked state. |

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-context-menu-trigger` | `trigger` | The wrapper that listens for `contextmenu`. |
| `ui-context-menu-content` | `menu` | The focusgroup wrapper around the items. |

### Accessibility

- The content has `role="menu"` and its items `role="menuitem"`, `menuitemcheckbox` or `menuitemradio`.
- Opening focuses the first enabled item. Arrow Up and Arrow Down move focus with wrap-around, Home and End jump to the
  ends, Enter and Space choose, Escape closes.
- The menu opens on any `contextmenu` event from the trigger. Browsers also fire it for the context menu key and
  Shift+F10 on a focused element, so put a focusable element in the trigger if keyboard users need the menu. Offer
  the same actions somewhere else as well.


---

# Dialog

Source: http://realm.js.org/components/dialog/

`ui-dialog` renders a native `<dialog>` in its shadow root and opens it with `showModal()`. The browser puts it in the
top layer, makes the rest of the page inert, moves focus into the dialog and returns focus to the trigger when it
closes. Escape, a click on the backdrop and the built-in close button all ask the dialog to close. A cancelable
`cancel` event lets you keep it open.

Build it from parts: `ui-dialog-trigger` opens it, `ui-dialog-header` holds the `ui-dialog-title` and
`ui-dialog-description`, the content goes in between, and `ui-dialog-footer` holds the actions. `ui-dialog-close`
closes the dialog when the element inside it is clicked.

```html live
<ui-dialog>
  <ui-dialog-trigger><ui-button variant="outline">Edit profile</ui-button></ui-dialog-trigger>
  <ui-dialog-header>
    <ui-dialog-title>Edit profile</ui-dialog-title>
    <ui-dialog-description>Make changes to your profile here. Click save when you are done.</ui-dialog-description>
  </ui-dialog-header>
  <ui-field>
    <ui-label for="dialog-profile-name">Name</ui-label>
    <ui-input id="dialog-profile-name" value="Pedro Duarte"></ui-input>
  </ui-field>
  <ui-dialog-footer>
    <ui-dialog-close><ui-button variant="outline">Cancel</ui-button></ui-dialog-close>
    <ui-dialog-close value="saved"><ui-button>Save changes</ui-button></ui-dialog-close>
  </ui-dialog-footer>
</ui-dialog>
```

## Examples

### Open and close with commands

The trigger part is the usual way to open the dialog. A button elsewhere on the page can open it too, because `ui-dialog`
listens for the `command` event that `commandfor` buttons send. It understands `--show-modal`, `--close` and
`--request-close`, with or without the `--` prefix. `--close` closes straight away. `--request-close` fires `cancel`
first, like Escape does. `ui-button` accepts either form. On a plain `<button>`, use the `--` form, because browsers with native
invoker commands only forward custom (`--`) commands to elements that are not a native `<dialog>`.

```html live
<ui-button commandfor="dialog-commands" command="--show-modal">Share</ui-button>
<ui-dialog id="dialog-commands">
  <ui-dialog-header>
    <ui-dialog-title>Share link</ui-dialog-title>
    <ui-dialog-description>Anyone with this link can view the document.</ui-dialog-description>
  </ui-dialog-header>
  <ui-input value="https://example.com/docs/a1b2c3" aria-label="Link" readonly></ui-input>
  <ui-dialog-footer>
    <ui-button variant="secondary" commandfor="dialog-commands" command="--request-close">Done</ui-button>
  </ui-dialog-footer>
</ui-dialog>
```

### Read the result

`ui-dialog-close value="…"` closes the dialog and stores the value in `returnValue`. From script, `close(value)` does
the same. The `close` event fires after the dialog has closed. Escape, the backdrop and the close button close it
without changing `returnValue`.

```html live
<custom-element name="dialog-script-demo">
  <script type="realm">
    const plan = useState({ current: "Free" });

    function closed() {
      plan.current = refs.dialog.returnValue || plan.current;
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 4);
      font-size: var(--text-sm);
    }
  </style>

  <ui-dialog ref="dialog" onclose="closed()">
    <ui-dialog-trigger><ui-button variant="outline">Change plan</ui-button></ui-dialog-trigger>
    <ui-dialog-header>
      <ui-dialog-title>Choose a plan</ui-dialog-title>
      <ui-dialog-description>You can switch plans at any time.</ui-dialog-description>
    </ui-dialog-header>
    <ui-dialog-footer>
      <ui-dialog-close value="Free"><ui-button variant="outline">Free</ui-button></ui-dialog-close>
      <ui-dialog-close value="Pro"><ui-button>Pro</ui-button></ui-dialog-close>
    </ui-dialog-footer>
  </ui-dialog>
  <span>Current plan: <strong><slot name="#plan.current"></slot></strong></span>
</custom-element>
<dialog-script-demo></dialog-script-demo>
```

### Side placement

`side` turns the dialog into a panel attached to an edge of the viewport: `top`, `right`, `bottom` or `left`. The
default is `center`. [Sheet](/components/sheet/) is a shorthand for this.

```html live
<custom-element name="dialog-side-demo">
  <script type="realm">
    const panel = useState({ side: "right" });

    function open(side) {
      panel.side = side;
      refs.dialog.showModal();
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      flex-wrap: wrap;
      gap: calc(var(--spacing) * 2);
    }
  </style>

  <ui-button variant="outline" onclick="open('top')">Top</ui-button>
  <ui-button variant="outline" onclick="open('right')">Right</ui-button>
  <ui-button variant="outline" onclick="open('bottom')">Bottom</ui-button>
  <ui-button variant="outline" onclick="open('left')">Left</ui-button>
  <ui-dialog ref="dialog" _side="#panel.side">
    <ui-dialog-header>
      <ui-dialog-title>Notifications</ui-dialog-title>
      <ui-dialog-description>Choose what you want to be notified about.</ui-dialog-description>
    </ui-dialog-header>
    <ui-dialog-footer>
      <ui-dialog-close><ui-button>Close</ui-button></ui-dialog-close>
    </ui-dialog-footer>
  </ui-dialog>
</custom-element>
<dialog-side-demo></dialog-side-demo>
```

### Persistent

`persistent` ignores Escape and backdrop clicks, so the dialog only closes through its own buttons. Combine it with
`hide-close` to remove the close button in the corner.

```html live
<ui-dialog persistent hide-close>
  <ui-dialog-trigger><ui-button variant="outline">Accept terms</ui-button></ui-dialog-trigger>
  <ui-dialog-header>
    <ui-dialog-title>Terms of service</ui-dialog-title>
    <ui-dialog-description>Please accept the updated terms to continue.</ui-dialog-description>
  </ui-dialog-header>
  <ui-dialog-footer>
    <ui-dialog-close value="declined"><ui-button variant="outline">Decline</ui-button></ui-dialog-close>
    <ui-dialog-close value="accepted"><ui-button>Accept</ui-button></ui-dialog-close>
  </ui-dialog-footer>
</ui-dialog>
```

### Keep it open on cancel

Escape, a backdrop click, the close button, `requestClose()` and the `--request-close` command fire a cancelable
`cancel` event before closing. Call `preventDefault()` to keep the dialog open, for example while a form has unsaved
changes. `close()`, `--close` and `ui-dialog-close` skip this step.

```html live
<custom-element name="dialog-cancel-demo">
  <script type="realm">
    function cancelled(event) {
      if (!refs.note.value) return;
      event.preventDefault();
      document.dispatchEvent(new CustomEvent("toast", { detail: { title: "Save or clear your note first" } }));
    }

    function save() {
      refs.note.value = "";
    }
  </script>

  <ui-dialog oncancel="cancelled(event)">
    <ui-dialog-trigger><ui-button variant="outline">Write a note</ui-button></ui-dialog-trigger>
    <ui-dialog-header>
      <ui-dialog-title>New note</ui-dialog-title>
      <ui-dialog-description>Type something, then try Escape or the close button.</ui-dialog-description>
    </ui-dialog-header>
    <ui-textarea ref="note" aria-label="Note" placeholder="Remember to..."></ui-textarea>
    <ui-dialog-footer>
      <ui-dialog-close value="saved"><ui-button onclick="save()">Save</ui-button></ui-dialog-close>
    </ui-dialog-footer>
  </ui-dialog>
</custom-element>
<dialog-cancel-demo></dialog-cancel-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-dialog` | | The modal `<dialog>`, a grid with a gap between the header, content and footer, plus the close button. |
| `ui-dialog-trigger` | `trigger` | Its content, outside the dialog. A click on it focuses the element inside and opens the dialog. |
| `ui-dialog-header` | `header` | A column for the title and description at the top of the dialog. |
| `ui-dialog-title` | (default) | An `<h2>` in `var(--text-lg)` semibold. Its text becomes the dialog's accessible name. |
| `ui-dialog-description` | (default) | A `<p>` in muted `var(--text-sm)`. Its text becomes the dialog's accessible description. |
| `ui-dialog-footer` | `footer` | A row of actions at the bottom, aligned to the end and wrapped on narrow screens. |
| `ui-dialog-close` | (default) | Its content. A click on it closes the dialog without firing `cancel`. |

Parts with a slot assign themselves to it, so you do not write `slot`. Everything else goes in the default slot, the
dialog body, in source order.

### ui-dialog attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | boolean | `false` | Whether the dialog is open. Setting it opens the dialog modally. Reflects. |
| `side` | `"center"` \| `"top"` \| `"right"` \| `"bottom"` \| `"left"` | `"center"` | Where the dialog sits. Any value other than `center` attaches it to that edge as a full-height or full-width panel. |
| `hide-close` | boolean | `false` | Hides the close button in the top corner. Property name: `hideClose`. |
| `persistent` | boolean | `false` | Ignores Escape and backdrop clicks. The close button and `requestClose()` still work. |
| `label` | string | | Accessible name when there is no `ui-dialog-title`. |
| `description` | string | | Accessible description when there is no `ui-dialog-description`. |

### ui-dialog-close attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | | Stored in the dialog's `returnValue` when it closes. Leave it out to keep the previous value. |

### Properties and methods

| Name | Description |
| --- | --- |
| `showModal()` | Opens the dialog modally. |
| `show()` | Same as `showModal()`. The dialog is always modal. |
| `close(value?)` | Closes the dialog. When `value` is given it becomes `returnValue`. Does not fire `cancel`. |
| `requestClose(value?)` | Fires `cancel`, then closes with `value` unless the event was cancelled. |
| `returnValue` | Read-only. The value passed to the last `close(value)` or `ui-dialog-close`, or `""`. |
| `open` | Boolean property mirroring the attribute. |

### Commands

| Command | Action |
| --- | --- |
| `--show-modal` | Opens the dialog. |
| `--close` | Closes the dialog. |
| `--request-close` | Same as `requestClose()`. |

`ui-button` also accepts `show-modal`, `close` and `request-close` without the prefix.

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `cancel` | none | Fired before the dialog closes from Escape, a backdrop click, the close button, `requestClose()` or `--request-close`. Cancelable. Does not bubble. |
| `close` | none | Fired after the dialog has closed, however it was closed. Does not bubble. |

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-dialog` | `dialog` | The native `<dialog>` element. Style the backdrop with `ui-dialog::part(dialog)::backdrop`. |
| `ui-dialog` | `body` | Wrapper around the default slot. In a centred dialog it adds no box of its own (`display: contents`), so empty content leaves no gap. In a left or right sheet it fills the remaining height. |
| `ui-dialog` | `close` | The close button in the top corner. |
| `ui-dialog-title` | `title` | The `<h2>`. |
| `ui-dialog-description` | `description` | The `<p>`. |
| `ui-dialog-trigger` | `trigger` | The wrapper that listens for clicks. |
| `ui-dialog-close` | `close` | The wrapper that listens for clicks. |

### Accessibility

- The inner `<dialog>` is opened with `showModal()`, so the page behind it is inert and focus is trapped inside.
- On open, focus moves to the first focusable element, or to an element with `autofocus`. On close it returns to the
  trigger.
- The text of `ui-dialog-title` and `ui-dialog-description` becomes the dialog's `aria-label` and
  `aria-description`, and updates when it changes. The title is also an `<h2>` heading.
- Escape closes the dialog unless `persistent` is set or the `cancel` event is cancelled.
- The close button has `aria-label="Close"`.


---

# Drawer

Source: http://realm.js.org/components/drawer/

`ui-drawer` is a modal `<dialog>` that slides in from an edge of the viewport, by default from the bottom. A bottom
drawer shows a drag handle. Drag it down more than 80 pixels to close the drawer. Escape and a click on the backdrop
also close it, and focus returns to the trigger.

Build it from `ui-drawer-trigger`, `ui-drawer-header` with `ui-drawer-title` and `ui-drawer-description`, the content,
and `ui-drawer-footer`. `ui-drawer-close` closes the drawer when the element inside it is clicked.

```html live
<ui-drawer>
  <ui-drawer-trigger><ui-button variant="outline">Set daily goal</ui-button></ui-drawer-trigger>
  <ui-drawer-header>
    <ui-drawer-title>Move goal</ui-drawer-title>
    <ui-drawer-description>Set your daily activity goal.</ui-drawer-description>
  </ui-drawer-header>
  <ui-slider value="350" min="200" max="600" step="10" aria-label="Calories per day"></ui-slider>
  <ui-drawer-footer>
    <ui-drawer-close><ui-button>Submit</ui-button></ui-drawer-close>
    <ui-drawer-close><ui-button variant="outline">Cancel</ui-button></ui-drawer-close>
  </ui-drawer-footer>
</ui-drawer>
```

## Examples

### Sides

Set `side` to `top`, `left` or `right`. Only the bottom drawer shows the drag handle.

```html live
<custom-element name="drawer-side-demo">
  <script type="realm">
    const panel = useState({ side: "bottom" });

    function open(side) {
      panel.side = side;
      refs.drawer.showModal();
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      flex-wrap: wrap;
      gap: calc(var(--spacing) * 2);
    }
  </style>

  <ui-button variant="outline" onclick="open('top')">Top</ui-button>
  <ui-button variant="outline" onclick="open('right')">Right</ui-button>
  <ui-button variant="outline" onclick="open('bottom')">Bottom</ui-button>
  <ui-button variant="outline" onclick="open('left')">Left</ui-button>
  <ui-drawer ref="drawer" _side="#panel.side">
    <ui-drawer-header>
      <ui-drawer-title>Recent activity</ui-drawer-title>
      <ui-drawer-description>You have three unread notifications.</ui-drawer-description>
    </ui-drawer-header>
    <ui-drawer-footer>
      <ui-drawer-close><ui-button variant="outline">Close</ui-button></ui-drawer-close>
    </ui-drawer-footer>
  </ui-drawer>
</custom-element>
<drawer-side-demo></drawer-side-demo>
```

### React to closing

`close` fires after the drawer closes, whether by a button, Escape, the backdrop or a drag.

```html live
<custom-element name="drawer-close-demo">
  <script type="realm">
    const share = useState({ status: "Not shared yet." });

    function pick(target) {
      share.status = `Shared to ${target}.`;
    }

    function closed() {
      document.dispatchEvent(new CustomEvent("toast", { detail: { title: "Drawer closed", description: share.status } }));
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 4);
      font-size: var(--text-sm);
    }
    .targets {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
  </style>

  <ui-drawer onclose="closed()">
    <ui-drawer-trigger><ui-button variant="outline">Share</ui-button></ui-drawer-trigger>
    <ui-drawer-header>
      <ui-drawer-title>Share</ui-drawer-title>
      <ui-drawer-description>Pick where to send this link.</ui-drawer-description>
    </ui-drawer-header>
    <div class="targets">
      <ui-drawer-close><ui-button variant="secondary" onclick="pick('Email')">Email</ui-button></ui-drawer-close>
      <ui-drawer-close><ui-button variant="secondary" onclick="pick('Messages')">Messages</ui-button></ui-drawer-close>
    </div>
  </ui-drawer>
  <span><slot name="#share.status"></slot></span>
</custom-element>
<drawer-close-demo></drawer-close-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-drawer` | | The modal `<dialog>` with the drag handle, a grid with a gap between the header, content and footer. |
| `ui-drawer-trigger` | `trigger` | Its content, outside the drawer. A click on it focuses the element inside and opens the drawer. |
| `ui-drawer-header` | `header` | A column for the title and description. |
| `ui-drawer-title` | (default) | An `<h2>` in `var(--text-base)` semibold. Its text becomes the drawer's accessible name. |
| `ui-drawer-description` | (default) | A `<p>` in muted `var(--text-sm)`. Its text becomes the drawer's accessible description. |
| `ui-drawer-footer` | `footer` | A column of full-width actions at the bottom. |
| `ui-drawer-close` | (default) | Its content. A click on it closes the drawer. |

Parts with a slot assign themselves to it, so you do not write `slot`. Everything else goes in the body in source
order.

### ui-drawer attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | boolean | `false` | Whether the drawer is open. Setting it opens the drawer modally. Reflects. |
| `side` | `"bottom"` \| `"top"` \| `"left"` \| `"right"` | `"bottom"` | The edge the drawer slides in from. |

### Properties and methods

| Name | Description |
| --- | --- |
| `showModal()` | Opens the drawer. |
| `show()` | Same as `showModal()`. |
| `close()` | Closes the drawer. |
| `open` | Boolean property mirroring the attribute. |

### Commands

| Command | Action |
| --- | --- |
| `--show-modal` | Opens the drawer. |
| `--close` | Closes the drawer. |
| `--request-close` | Same as `--close`. |

`ui-button` also accepts the commands without the `--` prefix. A plain `<button>` needs the prefix.

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `close` | none | Fired after the drawer has closed. Does not bubble. |

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-drawer` | `dialog` | The native `<dialog>` element. |
| `ui-drawer` | `handle` | The drag handle. Visible only when `side` is `bottom`. |
| `ui-drawer` | `body` | Wrapper around the default slot. It adds no box of its own (`display: contents`), so empty content leaves no gap. |
| `ui-drawer-title` | `title` | The `<h2>`. |
| `ui-drawer-description` | `description` | The `<p>`. |

### Accessibility

- The inner `<dialog>` is opened with `showModal()`, so the page behind it is inert and focus stays inside.
- The text of the title and description parts becomes the drawer's `aria-label` and `aria-description`.
- Escape and a backdrop click close the drawer. Focus returns to the trigger.
- The drag handle is a pointer shortcut only. Keyboard users close the drawer with Escape or a footer button.


---

# Dropdown Menu

Source: http://realm.js.org/components/dropdown-menu/

`ui-dropdown-menu` pairs a `ui-dropdown-menu-trigger` with a `ui-dropdown-menu-content`. The content is a native
`popover="auto"` element with `role="menu"`, anchored to the trigger with CSS anchor positioning, so it closes on
Escape, on a click outside and when focus leaves it. Opening moves focus to the first enabled item, the arrow keys
move between items and Enter or Space chooses one.

The items are shared with [Context Menu](/components/context-menu/) and [Menubar](/components/menubar/):
`ui-menu-item`, `ui-menu-checkbox-item`, `ui-menu-radio-group` with `ui-menu-radio-item`, `ui-menu-label`,
`ui-menu-group`, `ui-menu-separator` and `ui-menu-shortcut`. Choosing an item fires a `select` event with the item's
`value` and closes the menu.

```html live
<ui-dropdown-menu onselect="document.dispatchEvent(new CustomEvent('toast', { detail: { title: 'Selected ' + event.detail.value } }))">
  <ui-dropdown-menu-trigger><ui-button variant="outline">Open menu</ui-button></ui-dropdown-menu-trigger>
  <ui-dropdown-menu-content>
    <ui-menu-label>My Account</ui-menu-label>
    <ui-menu-group>
      <ui-menu-item value="profile">Profile <ui-menu-shortcut>⇧⌘P</ui-menu-shortcut></ui-menu-item>
      <ui-menu-item value="billing">Billing <ui-menu-shortcut>⌘B</ui-menu-shortcut></ui-menu-item>
      <ui-menu-item value="settings">Settings <ui-menu-shortcut>⌘S</ui-menu-shortcut></ui-menu-item>
    </ui-menu-group>
    <ui-menu-separator></ui-menu-separator>
    <ui-menu-item value="logout" variant="destructive">Log out <ui-menu-shortcut>⇧⌘Q</ui-menu-shortcut></ui-menu-item>
  </ui-dropdown-menu-content>
</ui-dropdown-menu>
```

## Examples

### Handle the selection

`select` bubbles from the item, so one listener on `ui-dropdown-menu` handles every item. `event.detail.value` is the
item's `value`.

```html live
<custom-element name="dropdown-menu-sort-demo">
  <script type="realm">
    const list = useState({ sort: "newest" });

    function sorted(event) {
      list.sort = event.detail.value;
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 4);
      font-size: var(--text-sm);
    }
  </style>

  <ui-dropdown-menu onselect="sorted(event)">
    <ui-dropdown-menu-trigger><ui-button variant="outline">Sort</ui-button></ui-dropdown-menu-trigger>
    <ui-dropdown-menu-content>
      <ui-menu-item value="newest">Newest first</ui-menu-item>
      <ui-menu-item value="oldest">Oldest first</ui-menu-item>
      <ui-menu-item value="name">Name</ui-menu-item>
    </ui-dropdown-menu-content>
  </ui-dropdown-menu>
  <span>Sorted by: <slot name="#list.sort"></slot></span>
</custom-element>
<dropdown-menu-sort-demo></dropdown-menu-sort-demo>
```

### Checkbox items

`ui-menu-checkbox-item` toggles its `checked` attribute when chosen. Its `select` event carries `{ value, checked }`.

```html live
<ui-dropdown-menu>
  <ui-dropdown-menu-trigger><ui-button variant="outline">View</ui-button></ui-dropdown-menu-trigger>
  <ui-dropdown-menu-content>
    <ui-menu-label>Appearance</ui-menu-label>
    <ui-menu-separator></ui-menu-separator>
    <ui-menu-checkbox-item value="status-bar" checked>Status Bar</ui-menu-checkbox-item>
    <ui-menu-checkbox-item value="activity-bar" disabled>Activity Bar</ui-menu-checkbox-item>
    <ui-menu-checkbox-item value="panel">Panel</ui-menu-checkbox-item>
  </ui-dropdown-menu-content>
</ui-dropdown-menu>
```

### Radio items

`ui-menu-radio-group` holds `ui-menu-radio-item` elements and keeps one of them checked. Its `value` attribute is the
checked item's value and updates when another item is chosen.

```html live
<ui-dropdown-menu>
  <ui-dropdown-menu-trigger><ui-button variant="outline">Panel position</ui-button></ui-dropdown-menu-trigger>
  <ui-dropdown-menu-content>
    <ui-menu-label>Panel Position</ui-menu-label>
    <ui-menu-separator></ui-menu-separator>
    <ui-menu-radio-group value="bottom">
      <ui-menu-radio-item value="top">Top</ui-menu-radio-item>
      <ui-menu-radio-item value="bottom">Bottom</ui-menu-radio-item>
      <ui-menu-radio-item value="right">Right</ui-menu-radio-item>
    </ui-menu-radio-group>
  </ui-dropdown-menu-content>
</ui-dropdown-menu>
```

### Icons, disabled and destructive items

A slotted `<svg>` is sized and muted. `disabled` items are skipped by the keyboard and ignore clicks.
`variant="destructive"` colours an item for dangerous actions.

```html live
<ui-dropdown-menu>
  <ui-dropdown-menu-trigger><ui-button variant="outline">Actions</ui-button></ui-dropdown-menu-trigger>
  <ui-dropdown-menu-content>
    <ui-menu-item value="edit">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M12 20h9M16.5 3.5a2.1 2.1 0 0 1 3 3L7 19l-4 1 1-4Z" /></svg>
      Edit
    </ui-menu-item>
    <ui-menu-item value="duplicate">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><rect x="8" y="8" width="12" height="12" rx="2" /><path d="M4 16V6a2 2 0 0 1 2-2h10" /></svg>
      Duplicate
    </ui-menu-item>
    <ui-menu-item value="share" disabled>
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M4 12v8h16v-8M12 3v12M7 8l5-5 5 5" /></svg>
      Share
    </ui-menu-item>
    <ui-menu-separator></ui-menu-separator>
    <ui-menu-item value="delete" variant="destructive">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M3 6h18M8 6V4h8v2M6 6l1 14h10l1-14" /></svg>
      Delete
    </ui-menu-item>
  </ui-dropdown-menu-content>
</ui-dropdown-menu>
```

### Placement

`placement` on `ui-dropdown-menu-content` sets where the menu opens relative to the trigger: `bottom-start` (default),
`bottom-end`, `top-start` or `top-end`. The menu flips when there is not enough room.

```html live
<div class="demo-row-tight">
  <ui-dropdown-menu>
    <ui-dropdown-menu-trigger><ui-button variant="outline">Bottom end</ui-button></ui-dropdown-menu-trigger>
    <ui-dropdown-menu-content placement="bottom-end">
      <ui-menu-item value="one">First item</ui-menu-item>
      <ui-menu-item value="two">Second item</ui-menu-item>
    </ui-dropdown-menu-content>
  </ui-dropdown-menu>
  <ui-dropdown-menu>
    <ui-dropdown-menu-trigger><ui-button variant="outline">Top start</ui-button></ui-dropdown-menu-trigger>
    <ui-dropdown-menu-content placement="top-start">
      <ui-menu-item value="one">First item</ui-menu-item>
      <ui-menu-item value="two">Second item</ui-menu-item>
    </ui-dropdown-menu-content>
  </ui-dropdown-menu>
</div>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-dropdown-menu` | | Its parts, with no box of its own. |
| `ui-dropdown-menu-trigger` | (default) | An inline block around the trigger. A click on it focuses the element inside and toggles the menu. |
| `ui-dropdown-menu-content` | (default) | A bordered `popover="auto"` panel with `role="menu"`, anchored to the trigger. |
| `ui-menu-item` | (default) | A row with `role="menuitem"`: an optional leading `<svg>`, the label and an optional shortcut. |
| `ui-menu-checkbox-item` | (default) | A row with `role="menuitemcheckbox"` and a check mark when `checked`. |
| `ui-menu-radio-group` | (default) | A group (`role="group"`) that keeps one radio item checked. |
| `ui-menu-radio-item` | (default) | A row with `role="menuitemradio"` and a dot when checked. Place it in `ui-menu-radio-group`. |
| `ui-menu-label` | (default) | A heading row in `var(--text-sm)` medium. Not focusable. |
| `ui-menu-group` | (default) | A block with `role="group"` around related items. |
| `ui-menu-separator` | (default) | A one-pixel line with `role="separator"`. |
| `ui-menu-shortcut` | (default) | Muted `var(--text-xs)` text pushed to the end of its item. Place it in an item. |

The `ui-menu-*` parts work the same in `ui-context-menu-content` and `ui-menubar-content`.

### ui-dropdown-menu-content attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `"bottom-start"` \| `"bottom-end"` \| `"top-start"` \| `"top-end"` | `"bottom-start"` | Where the menu opens relative to the trigger. |

### ui-menu-item attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | | Sent as `event.detail.value` when the item is chosen. |
| `disabled` | boolean | `false` | Ignores clicks and keys, sets `aria-disabled` and skips the item in keyboard navigation. |
| `variant` | `"default"` \| `"destructive"` | `"default"` | Destructive items use the destructive colour. |

### ui-menu-checkbox-item attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | | Sent in `event.detail.value`. |
| `checked` | boolean | `false` | Whether the item is checked. Toggled when chosen. Reflects. |
| `disabled` | boolean | `false` | Ignores clicks and keys and skips the item in keyboard navigation. |

### ui-menu-radio-group and ui-menu-radio-item attributes

| Element | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `ui-menu-radio-group` | `value` | string | | The checked item's value. Updated when an item is chosen. Reflects. |
| `ui-menu-radio-item` | `value` | string | | The item's value. |
| `ui-menu-radio-item` | `disabled` | boolean | `false` | Ignores clicks and keys and skips the item in keyboard navigation. |

### Events

| Event | Element | Detail | Description |
| --- | --- | --- | --- |
| `select` | `ui-menu-item`, `ui-menu-radio-item` | `{ value }` | Fired when an enabled item is clicked or activated with Enter or Space. Bubbles and is composed, so you can listen on `ui-dropdown-menu`. The menu closes afterwards. |
| `select` | `ui-menu-checkbox-item` | `{ value, checked }` | Same, with the new checked state. |

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-dropdown-menu-trigger` | `trigger` | The wrapper that listens for clicks. It is the anchor for positioning. |
| `ui-dropdown-menu-content` | `menu` | The focusgroup wrapper around the items. |
| `ui-menu-checkbox-item`, `ui-menu-radio-item` | `indicator` | The check mark or dot. |

### CSS states

| Name | Description |
| --- | --- |
| `ui-menu-item:state(attr-disabled)` | Matches disabled items. |
| `ui-menu-item:state(attr-variant-is-destructive)` | Matches destructive items. |
| `ui-menu-checkbox-item:state(attr-checked)` | Matches checked checkbox items. Radio items have the same state. |
| `ui-dropdown-menu-content:popover-open` | Matches while the menu is open. |

### Accessibility

- The content has `role="menu"`. Items have `role="menuitem"`, `menuitemcheckbox` or `menuitemradio` with
  `aria-checked`, and `tabindex="-1"`. Groups and the radio group have `role="group"`, separators `role="separator"`.
- Opening the menu focuses the first enabled item. Arrow Up and Arrow Down move focus and wrap around. Home and End
  jump to the first and last item.
- Enter and Space choose the focused item. Escape, a click outside or moving focus out of the menu closes it.
- When the menu closes with focus inside it, focus returns to the trigger.


---

# Hover Card

Source: http://realm.js.org/components/hover-card/

`ui-hover-card` shows a floating card next to its trigger after the pointer has rested on it for a moment, or when the
trigger receives keyboard focus. Put the link in `ui-hover-card-trigger` and the card in `ui-hover-card-content`. The
card stays open while the pointer is over it, so users can move into it and click links. It is a `popover="manual"`
element anchored to the trigger, so it does not close other popovers and is not light dismissed.

Use it for previews that sighted mouse users can do without, such as a profile summary behind a username link. Put
anything essential in the page itself.

```html live
<ui-hover-card>
  <ui-hover-card-trigger><ui-button variant="link">@realmorg</ui-button></ui-hover-card-trigger>
  <ui-hover-card-content width="80">
    <div class="demo-media">
      <ui-avatar><ui-avatar-fallback>R</ui-avatar-fallback></ui-avatar>
      <div class="demo-stack-tight">
        <strong class="demo-text">@realmorg</strong>
        <span class="demo-text">Native-first custom elements, written as HTML.</span>
        <span class="demo-muted">Joined December 2021</span>
      </div>
    </div>
  </ui-hover-card-content>
</ui-hover-card>
```

## Examples

### Delays

`open-delay` on `ui-hover-card` is the time in milliseconds before the card opens (default `500`). `close-delay` is the
time before it closes after the pointer or focus leaves (default `300`).

```html live
<div class="demo-row">
  <ui-hover-card open-delay="0" close-delay="0">
    <ui-hover-card-trigger><ui-button variant="link">Instant</ui-button></ui-hover-card-trigger>
    <ui-hover-card-content>Opens and closes without delay.</ui-hover-card-content>
  </ui-hover-card>
  <ui-hover-card open-delay="1000" close-delay="1000">
    <ui-hover-card-trigger><ui-button variant="link">Slow</ui-button></ui-hover-card-trigger>
    <ui-hover-card-content>Waits a second before opening and before closing.</ui-hover-card-content>
  </ui-hover-card>
</div>
```

### Placement and width

`placement` on `ui-hover-card-content` puts the card `bottom` (default), `top`, `left` or `right` of the trigger. It
flips when there is not enough room. `width` sets the card width in spacing units (default `64`).

```html live
<div class="demo-row-tight">
  <ui-hover-card open-delay="100">
    <ui-hover-card-trigger><ui-button variant="outline">Top</ui-button></ui-hover-card-trigger>
    <ui-hover-card-content placement="top">Card above the trigger.</ui-hover-card-content>
  </ui-hover-card>
  <ui-hover-card open-delay="100">
    <ui-hover-card-trigger><ui-button variant="outline">Right</ui-button></ui-hover-card-trigger>
    <ui-hover-card-content placement="right" width="48">Card to the right.</ui-hover-card-content>
  </ui-hover-card>
  <ui-hover-card open-delay="100">
    <ui-hover-card-trigger><ui-button variant="outline">Bottom</ui-button></ui-hover-card-trigger>
    <ui-hover-card-content placement="bottom">Card below the trigger.</ui-hover-card-content>
  </ui-hover-card>
  <ui-hover-card open-delay="100">
    <ui-hover-card-trigger><ui-button variant="outline">Left</ui-button></ui-hover-card-trigger>
    <ui-hover-card-content placement="left" width="48">Card to the left.</ui-hover-card-content>
  </ui-hover-card>
</div>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-hover-card` | | Its parts, with no box of its own. Holds the delays. |
| `ui-hover-card-trigger` | (default) | An inline block around the trigger. Pointer enter and focus schedule the card to open. Pointer leave and focus out schedule it to close. |
| `ui-hover-card-content` | (default) | A bordered `popover="manual"` panel with padding, anchored to the trigger. The pointer over it keeps it open. |

### ui-hover-card attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `open-delay` | number | `500` | Milliseconds before the card opens. Minimum `0`. Property name: `openDelay`. |
| `close-delay` | number | `300` | Milliseconds before the card closes. Minimum `0`. Property name: `closeDelay`. |

### ui-hover-card-content attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `"bottom"` \| `"top"` \| `"left"` \| `"right"` | `"bottom"` | Side of the trigger the card appears on. |
| `width` | number | `64` | Card width in spacing units, where `n` means `calc(var(--spacing) * n)`. |

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-hover-card-trigger` | `trigger` | The wrapper that listens for pointer and focus events. |
| `ui-hover-card-content` | `content` | The padded box inside the card. |

### Accessibility

- The card opens on pointer enter and on focus inside the trigger, and closes on pointer leave and focus out.
- The card is not announced or linked to the trigger with ARIA. Treat it as a visual preview.
- Escape closes the card, wherever focus is. Moving focus away also closes it.


---

# Popover

Source: http://realm.js.org/components/popover/

`ui-popover` pairs a `ui-popover-trigger` with a `ui-popover-content`. The content is the native
[popover API](https://developer.mozilla.org/docs/Web/API/Popover_API) with a card style. It sets `popover="auto"` on
itself, so it starts hidden, opens in the top layer, closes when you click outside or press Escape, and closes other
`auto` popovers when it opens. A click on the trigger toggles it, and it is placed next to the trigger with CSS anchor
positioning, flipping when there is not enough room.

`ui-popover-header`, `ui-popover-title` and `ui-popover-description` lay out a heading inside the content.

```html live
<ui-popover>
  <ui-popover-trigger><ui-button variant="outline">Open popover</ui-button></ui-popover-trigger>
  <ui-popover-content width="80">
    <ui-popover-header>
      <ui-popover-title>Dimensions</ui-popover-title>
      <ui-popover-description>Set the dimensions for the layer.</ui-popover-description>
    </ui-popover-header>
    <ui-field orientation="horizontal">
      <ui-label for="popover-width">Width</ui-label>
      <ui-input id="popover-width" value="100%"></ui-input>
    </ui-field>
    <ui-field orientation="horizontal">
      <ui-label for="popover-height">Height</ui-label>
      <ui-input id="popover-height" value="25px"></ui-input>
    </ui-field>
  </ui-popover-content>
</ui-popover>
```

## Examples

### Placement

`placement` on `ui-popover-content` puts it `bottom` (default), `top`, `left` or `right` of the trigger.

```html live
<div class="demo-row-tight">
  <ui-popover>
    <ui-popover-trigger><ui-button variant="outline">Top</ui-button></ui-popover-trigger>
    <ui-popover-content placement="top" width="48">Placed above the button.</ui-popover-content>
  </ui-popover>
  <ui-popover>
    <ui-popover-trigger><ui-button variant="outline">Right</ui-button></ui-popover-trigger>
    <ui-popover-content placement="right" width="48">Placed to the right.</ui-popover-content>
  </ui-popover>
  <ui-popover>
    <ui-popover-trigger><ui-button variant="outline">Bottom</ui-button></ui-popover-trigger>
    <ui-popover-content placement="bottom" width="48">Placed below the button.</ui-popover-content>
  </ui-popover>
  <ui-popover>
    <ui-popover-trigger><ui-button variant="outline">Left</ui-button></ui-popover-trigger>
    <ui-popover-content placement="left" width="48">Placed to the left.</ui-popover-content>
  </ui-popover>
</div>
```

### Open with popovertarget or a command

`ui-popover-content` is a native popover, so a button anywhere on the page can open it by id with `popovertarget`, or
`commandfor` with `command="toggle-popover"`, `"show-popover"` or `"hide-popover"`. The popover is then anchored to that
button. A close button inside the popover can use `hide-popover`.

```html live
<div class="demo-row-tight">
  <ui-button variant="outline" popovertarget="popover-target">Pinned note</ui-button>
  <ui-popover-content id="popover-target">Opened with popovertarget.</ui-popover-content>
  <ui-button variant="outline" commandfor="popover-command" command="toggle-popover">Notifications</ui-button>
  <ui-popover-content id="popover-command">
    <span class="demo-text">You are all caught up.</span>
    <ui-button size="sm" variant="secondary" commandfor="popover-command" command="hide-popover">Dismiss</ui-button>
  </ui-popover-content>
</div>
```

### Open from script

Call the native `showPopover()`, `hidePopover()` or `togglePopover()` on `ui-popover-content`. Pass `{ source }` so it
is anchored to the element that opened it. The native `toggle` event reports the new state.

```html live
<custom-element name="popover-script-demo">
  <script type="realm">
    const info = useState({ state: "closed" });

    function show() {
      refs.popover.showPopover({ source: refs.trigger });
    }

    function toggled(event) {
      info.state = event.newState;
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 4);
      font-size: var(--text-sm);
    }
  </style>

  <ui-button ref="trigger" variant="outline" onclick="show()">Show details</ui-button>
  <span>Popover is <slot name="#info.state"></slot></span>
  <ui-popover-content ref="popover" ontoggle="toggled(event)">Opened with showPopover(). Press Escape to close.</ui-popover-content>
</custom-element>
<popover-script-demo></popover-script-demo>
```

### Manual popovers

Set `popover="manual"` on the content yourself to turn off light dismiss. A manual popover stays open until it is
toggled again or hidden from script.

```html live
<ui-popover>
  <ui-popover-trigger><ui-button variant="outline">Toggle pinned note</ui-button></ui-popover-trigger>
  <ui-popover-content popover="manual">This note stays open when you click elsewhere. Click the button again to hide it.</ui-popover-content>
</ui-popover>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-popover` | | Its parts, with no box of its own. |
| `ui-popover-trigger` | (default) | An inline block around the trigger. A click on it focuses the element inside and toggles the content, anchored to the trigger. |
| `ui-popover-content` | (default) | A bordered card with padding, a gap between children and `popover="auto"`. |
| `ui-popover-header` | (default) | A column for the title and description, with a small gap. |
| `ui-popover-title` | (default) | An `<h3>` in `var(--text-sm)` medium. |
| `ui-popover-description` | (default) | A `<p>` in muted `var(--text-sm)`. |

### ui-popover-content attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `"bottom"` \| `"top"` \| `"left"` \| `"right"` | `"bottom"` | Side of the anchor the popover appears on. It flips when there is not enough room. |
| `width` | number | `72` | Width in spacing units, where `n` means `calc(var(--spacing) * n)`. |
| `popover` | `"auto"` \| `"manual"` | `"auto"` | The native popover attribute. Set on connect when missing. |

### Properties and methods

`ui-popover-content` has the native popover methods: `showPopover(options?)`, `hidePopover()` and
`togglePopover(options?)`. Use `:popover-open` to check whether it is open.

### Events

| Event | Element | Detail | Description |
| --- | --- | --- | --- |
| `beforetoggle` | `ui-popover-content` | `ToggleEvent` | Native. Fired before the popover opens or closes. Cancelable when opening. |
| `toggle` | `ui-popover-content` | `ToggleEvent` | Native. Fired after it opens or closes. `event.newState` is `"open"` or `"closed"`. |

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-popover-trigger` | `trigger` | The wrapper that listens for clicks. |
| `ui-popover-title` | `title` | The `<h3>`. |
| `ui-popover-description` | `description` | The `<p>`. |

### CSS states

| Name | Description |
| --- | --- |
| `ui-popover-content:popover-open` | Native pseudo-class that matches while the popover is shown. |

### Accessibility

- Opened by a button with `popovertarget` or `commandfor`, the browser sets `aria-expanded` on that button and links
  it to the popover.
- Escape and a click outside close an `auto` popover. When it closes with focus inside, focus returns to the trigger.
- Without CSS anchor positioning support, the popover is centred in the viewport instead.


---

# Sheet

Source: http://realm.js.org/components/sheet/

`ui-sheet` is a modal panel attached to one edge of the viewport. It is a thin wrapper around
[Dialog](/components/dialog/) with `side` set, and behaves the same way. It opens with `showModal()`, traps focus,
closes on Escape, a backdrop click or the close button, and returns focus to the trigger when it closes. The default
side is `right`.

It has the same parts as the dialog: `ui-sheet-trigger`, `ui-sheet-header` with `ui-sheet-title` and
`ui-sheet-description`, `ui-sheet-footer` and `ui-sheet-close`.

```html live
<ui-sheet>
  <ui-sheet-trigger><ui-button variant="outline">Open sheet</ui-button></ui-sheet-trigger>
  <ui-sheet-header>
    <ui-sheet-title>Edit profile</ui-sheet-title>
    <ui-sheet-description>Make changes to your profile here. Click save when you are done.</ui-sheet-description>
  </ui-sheet-header>
  <ui-field>
    <ui-label for="sheet-profile-name">Name</ui-label>
    <ui-input id="sheet-profile-name" value="Pedro Duarte"></ui-input>
  </ui-field>
  <ui-field>
    <ui-label for="sheet-profile-username">Username</ui-label>
    <ui-input id="sheet-profile-username" value="@peduarte"></ui-input>
  </ui-field>
  <ui-sheet-footer>
    <ui-sheet-close><ui-button>Save changes</ui-button></ui-sheet-close>
  </ui-sheet-footer>
</ui-sheet>
```

## Examples

### Sides

Set `side` to `top`, `right`, `bottom` or `left`. Left and right sheets are full height. Top and bottom sheets are
full width.

```html live
<custom-element name="sheet-side-demo">
  <script type="realm">
    const panel = useState({ side: "right" });

    function open(side) {
      panel.side = side;
      refs.sheet.showModal();
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      flex-wrap: wrap;
      gap: calc(var(--spacing) * 2);
    }
    nav {
      display: grid;
      gap: calc(var(--spacing) * 2);
      font-size: var(--text-sm);
    }
  </style>

  <ui-button variant="outline" onclick="open('top')">Top</ui-button>
  <ui-button variant="outline" onclick="open('right')">Right</ui-button>
  <ui-button variant="outline" onclick="open('bottom')">Bottom</ui-button>
  <ui-button variant="outline" onclick="open('left')">Left</ui-button>
  <ui-sheet ref="sheet" _side="#panel.side">
    <ui-sheet-header>
      <ui-sheet-title>Menu</ui-sheet-title>
      <ui-sheet-description>Jump to a section of the app.</ui-sheet-description>
    </ui-sheet-header>
    <nav>
      <a href="#sheet-overview">Overview</a>
      <a href="#sheet-projects">Projects</a>
      <a href="#sheet-settings">Settings</a>
    </nav>
    <ui-sheet-footer>
      <ui-sheet-close><ui-button variant="outline">Close</ui-button></ui-sheet-close>
    </ui-sheet-footer>
  </ui-sheet>
</custom-element>
<sheet-side-demo></sheet-side-demo>
```

### React to closing

`close` fires on the sheet after it closes, however it was closed.

```html live
<custom-element name="sheet-close-demo">
  <script type="realm">
    const filters = useState({ closed: 0 });

    function closed() {
      filters.closed++;
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 4);
      font-size: var(--text-sm);
    }
  </style>

  <ui-sheet side="left" onclose="closed()">
    <ui-sheet-trigger><ui-button variant="outline">Filters</ui-button></ui-sheet-trigger>
    <ui-sheet-header>
      <ui-sheet-title>Filters</ui-sheet-title>
      <ui-sheet-description>Press Escape or click outside to close.</ui-sheet-description>
    </ui-sheet-header>
  </ui-sheet>
  <span>Closed <slot name="#filters.closed"></slot> times</span>
</custom-element>
<sheet-close-demo></sheet-close-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-sheet` | | A `ui-dialog` attached to the `side` edge. |
| `ui-sheet-trigger` | `trigger` | Its content, outside the sheet. A click on it focuses the element inside and opens the sheet. |
| `ui-sheet-header` | `header` | A column for the title and description at the top. |
| `ui-sheet-title` | (default) | An `<h2>` in `var(--text-lg)` semibold. Its text becomes the sheet's accessible name. |
| `ui-sheet-description` | (default) | A `<p>` in muted `var(--text-sm)`. Its text becomes the sheet's accessible description. |
| `ui-sheet-footer` | `footer` | A row of actions at the bottom, aligned to the end. |
| `ui-sheet-close` | (default) | Its content. A click on it closes the sheet. |

Parts with a slot assign themselves to it, so you do not write `slot`. Everything else goes in the body in source
order.

### ui-sheet attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | boolean | `false` | Whether the sheet is open. Setting it opens the sheet modally. Reflects. |
| `side` | `"top"` \| `"right"` \| `"bottom"` \| `"left"` | `"right"` | The edge the sheet is attached to. |

### Properties and methods

| Name | Description |
| --- | --- |
| `showModal()` | Opens the sheet. |
| `show()` | Same as `showModal()`. |
| `close()` | Closes the sheet. |
| `requestClose()` | Fires `cancel` on the inner dialog, then closes unless it was cancelled. |
| `open` | Boolean property mirroring the attribute. |

### Commands

| Command | Action |
| --- | --- |
| `--show-modal` | Opens the sheet. |
| `--close` | Closes the sheet. |
| `--request-close` | Same as `requestClose()`. |

`ui-button` also accepts the commands without the `--` prefix. A plain `<button>` needs the prefix.

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `close` | none | Fired after the sheet has closed. Does not bubble. |

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-sheet` | `dialog` | The inner `ui-dialog` element. Its own parts are not exported. |
| `ui-sheet-title` | `title` | The `<h2>`. |
| `ui-sheet-description` | `description` | The `<p>`. |

### Accessibility

`ui-sheet` inherits the behaviour of `ui-dialog`. The page behind it is inert, focus moves into the sheet on open and
back to the trigger on close, Escape and a backdrop click close it, and the close button has `aria-label="Close"`. The
title and description text name and describe the sheet.


---

# Toaster

Source: http://realm.js.org/components/toaster/

`ui-toaster` shows toasts, which are brief notifications stacked in a corner of the viewport. Place one `<ui-toaster>` per
page, usually at the end of `<body>`. It listens for a `toast` event on `document`, so any script or component can
show a toast without a reference to the toaster:

```js
document.dispatchEvent(new CustomEvent("toast", { detail: { title: "Saved" } }));
```

The toast list is a `popover="manual"` element in the top layer with `aria-live="polite"`, so screen readers announce
new toasts. Each toast closes after `duration` milliseconds or when its dismiss button is clicked.

This page already has a `ui-toaster`, so the demos below only send `toast` events or call its methods.

```html live
<ui-button variant="outline" onclick="document.dispatchEvent(new CustomEvent('toast', { detail: { title: 'Event created', description: 'Sunday, December 3 at 9:00 AM' } }))">Show toast</ui-button>
```

## Examples

### Destructive

`variant: "destructive"` colours the toast for errors.

```html live
<ui-button variant="outline" onclick="document.dispatchEvent(new CustomEvent('toast', { detail: { title: 'Upload failed', description: 'The file is larger than 10 MB.', variant: 'destructive' } }))">Show error</ui-button>
```

### From a component

Inside a component, dispatch the same event from a script function.

```html live
<custom-element name="toaster-save-demo">
  <script type="realm">
    const draft = useState({ saves: 0 });

    function save() {
      draft.saves++;
      document.dispatchEvent(
        new CustomEvent("toast", { detail: { title: "Draft saved", description: `Version ${draft.saves}` } }),
      );
    }
  </script>

  <ui-button onclick="save()">Save draft</ui-button>
</custom-element>
<toaster-save-demo></toaster-save-demo>
```

### Sticky toasts and dismissing from script

`duration` in the detail overrides the toaster's default for one toast. `0` keeps it open until it is dismissed. The
`toast()` method returns an id that you can pass to `dismiss()`.

```html live
<custom-element name="toaster-sticky-demo">
  <script type="realm">
    const upload = useState({ id: 0 });

    function start() {
      if (upload.id) return;
      upload.id = document.querySelector("ui-toaster").toast({ title: "Uploading...", description: "Keep this tab open.", duration: 0 });
    }

    function finish() {
      if (!upload.id) return;
      document.querySelector("ui-toaster").dismiss(upload.id);
      upload.id = 0;
      document.dispatchEvent(new CustomEvent("toast", { detail: { title: "Upload complete" } }));
    }
  </script>

  <style type="realm">
    :host {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
  </style>

  <ui-button variant="outline" onclick="start()">Start upload</ui-button>
  <ui-button variant="outline" onclick="finish()">Finish upload</ui-button>
</custom-element>
<toaster-sticky-demo></toaster-sticky-demo>
```

### Position and duration

Set `position` and `duration` on the page's toaster. Toasts stack from the chosen corner or edge.

```html
<ui-toaster position="top-center" duration="6000"></ui-toaster>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-toaster` | | The fixed toast list. Each toast is rendered from the data passed to `toast()` or the `toast` event, so there are no toast parts to write. |

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `"bottom-right"` \| `"bottom-left"` \| `"bottom-center"` \| `"top-right"` \| `"top-left"` \| `"top-center"` | `"bottom-right"` | Where toasts appear. |
| `duration` | number | `4000` | Default milliseconds before a toast closes. `0` keeps toasts open until dismissed. Minimum `0`. |

### Toast options

The `detail` of a `toast` event and the argument of `toast()` take the same fields. All are optional.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | string | `""` | Bold first line. |
| `description` | string | `""` | Muted second line. Hidden when empty. |
| `variant` | `"default"` \| `"destructive"` | `"default"` | Destructive toasts use the destructive colour. |
| `duration` | number | the `duration` attribute | Milliseconds before this toast closes. `0` keeps it open. |

### Properties and methods

| Name | Description |
| --- | --- |
| `toast(options?)` | Shows a toast and returns its numeric id. |
| `dismiss(id)` | Removes the toast with that id. Unknown ids are ignored. |

### Events

| Event | Target | Detail | Description |
| --- | --- | --- | --- |
| `toast` | `document` | toast options | Listened for, not dispatched. Every connected `ui-toaster` shows a toast for each event. |

### CSS parts

| Part | Description |
| --- | --- |
| `region` | The `<ol>` that holds the toasts (`popover="manual"`, `aria-live="polite"`). |
| `toast` | Each toast `<li>`. Destructive toasts have `data-variant="destructive"`. |

### Accessibility

- The list is a polite live region, so new toasts are announced without moving focus.
- Each toast has a dismiss button with `aria-label="Dismiss"`.
- Toasts close on their own. Do not put the only copy of important information or actions in a toast.


---

# Tooltip

Source: http://realm.js.org/components/tooltip/

`ui-tooltip` shows a small label next to its trigger when the pointer enters it or it receives focus. Put the element
in `ui-tooltip-trigger` and the label in `ui-tooltip-content`. The content is a `role="tooltip"` element shown as a
`popover="manual"`, so it renders in the top layer, is anchored to the trigger and does not close other popovers. It
hides on pointer leave, focus out and Escape.

```html live
<ui-tooltip>
  <ui-tooltip-trigger><ui-button variant="outline">Hover me</ui-button></ui-tooltip-trigger>
  <ui-tooltip-content>Add to library</ui-tooltip-content>
</ui-tooltip>
```

## Examples

### Placement

`placement` on `ui-tooltip-content` puts the tooltip `top` (default), `bottom`, `left` or `right` of the trigger. A
tooltip that does not fit flips to the opposite side.

```html live
<div class="demo-row-tight">
  <ui-tooltip>
    <ui-tooltip-trigger><ui-button variant="outline">Top</ui-button></ui-tooltip-trigger>
    <ui-tooltip-content placement="top">Above</ui-tooltip-content>
  </ui-tooltip>
  <ui-tooltip>
    <ui-tooltip-trigger><ui-button variant="outline">Right</ui-button></ui-tooltip-trigger>
    <ui-tooltip-content placement="right">To the right</ui-tooltip-content>
  </ui-tooltip>
  <ui-tooltip>
    <ui-tooltip-trigger><ui-button variant="outline">Bottom</ui-button></ui-tooltip-trigger>
    <ui-tooltip-content placement="bottom">Below</ui-tooltip-content>
  </ui-tooltip>
  <ui-tooltip>
    <ui-tooltip-trigger><ui-button variant="outline">Left</ui-button></ui-tooltip-trigger>
    <ui-tooltip-content placement="left">To the left</ui-tooltip-content>
  </ui-tooltip>
</div>
```

### Icon buttons

Tooltips suit icon-only buttons. Keep the button's own `aria-label`, because the tooltip text becomes the button's
description, not its name.

```html live
<div class="demo-row-tight">
  <ui-tooltip>
    <ui-tooltip-trigger>
      <ui-button variant="ghost" size="icon" aria-label="Bold">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M6 12h9a4 4 0 0 1 0 8H6V4h8a4 4 0 0 1 0 8" /></svg>
      </ui-button>
    </ui-tooltip-trigger>
    <ui-tooltip-content>Bold</ui-tooltip-content>
  </ui-tooltip>
  <ui-tooltip>
    <ui-tooltip-trigger>
      <ui-button variant="ghost" size="icon" aria-label="Italic">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M19 4h-9M14 20H5M15 4 9 20" /></svg>
      </ui-button>
    </ui-tooltip-trigger>
    <ui-tooltip-content>Italic</ui-tooltip-content>
  </ui-tooltip>
</div>
```

### Rich content and delay

`ui-tooltip-content` can hold markup such as a keyboard shortcut. `delay` on `ui-tooltip` sets the milliseconds before
the tooltip appears (default `300`). Hiding is immediate.

```html live
<ui-tooltip delay="0">
  <ui-tooltip-trigger><ui-button variant="outline">Save</ui-button></ui-tooltip-trigger>
  <ui-tooltip-content>Save draft <ui-kbd>Ctrl S</ui-kbd></ui-tooltip-content>
</ui-tooltip>
```

### Dynamic content

The content can be bound from a component's state. The trigger's description follows it.

```html live
<custom-element name="tooltip-copy-demo">
  <script type="realm">
    const copy = useState({ label: "Copy link" });

    function copied() {
      copy.label = "Copied";
    }

    function reset() {
      copy.label = "Copy link";
    }
  </script>

  <ui-tooltip delay="0">
    <ui-tooltip-trigger onpointerleave="reset()"><ui-button variant="outline" onclick="copied()">Share</ui-button></ui-tooltip-trigger>
    <ui-tooltip-content><slot name="#copy.label"></slot></ui-tooltip-content>
  </ui-tooltip>
</custom-element>
<tooltip-copy-demo></tooltip-copy-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-tooltip` | | Its parts, with no box of its own. |
| `ui-tooltip-trigger` | (default) | An inline block around the trigger. Pointer enter and focus show the tooltip. Pointer leave, focus out and Escape hide it. |
| `ui-tooltip-content` | (default) | A `popover="manual"` element with `role="tooltip"`, in `var(--text-xs)` on the foreground colour, anchored to the trigger. |

### ui-tooltip attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | number | `300` | Milliseconds before the tooltip opens. Minimum `0`. |

### ui-tooltip-content attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `"top"` \| `"bottom"` \| `"left"` \| `"right"` | `"top"` | Side of the trigger the tooltip appears on. |

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-tooltip-trigger` | `trigger` | The wrapper that listens for pointer and focus events. |

### CSS states

| Name | Description |
| --- | --- |
| `ui-tooltip-content:popover-open` | Matches while the tooltip is shown. |

### Accessibility

- The content has `role="tooltip"` and opens on focus as well as hover, so keyboard users see it.
- Escape hides it while focus is on the trigger.
- The tooltip text is set as `aria-description` on each element in `ui-tooltip-trigger` (`ui-button` passes it to its
  inner button). Give the trigger its own accessible name.


---

# Accordion

Source: http://realm.js.org/components/accordion/

`ui-accordion` groups `ui-accordion-item` elements. Each item renders a native `<details>` and `<summary>` in its
shadow root, so the browser handles opening and closing, keyboard activation and find-in-page. Put a
`ui-accordion-trigger` and a `ui-accordion-content` inside each item. The trigger becomes the summary row, and the
content shows when the item is open. In the default `single` mode, opening one item closes the others. With
`type="multiple"` items open and close independently.

The accordion fills the width of its container.

```html live
<div class="demo-narrow">
  <ui-accordion>
    <ui-accordion-item open>
      <ui-accordion-trigger>Is it accessible?</ui-accordion-trigger>
      <ui-accordion-content>
        Yes. Each item is a native details element, so it works with the keyboard and screen readers.
      </ui-accordion-content>
    </ui-accordion-item>
    <ui-accordion-item>
      <ui-accordion-trigger>Is it styled?</ui-accordion-trigger>
      <ui-accordion-content>
        Yes. It uses the theme tokens, so it follows your colours, radii and dark mode.
      </ui-accordion-content>
    </ui-accordion-item>
    <ui-accordion-item>
      <ui-accordion-trigger>Is it animated?</ui-accordion-trigger>
      <ui-accordion-content>The chevron rotates when an item opens.</ui-accordion-content>
    </ui-accordion-item>
  </ui-accordion>
</div>
```

## Examples

### Multiple open items

Set `type="multiple"` to let several items stay open at once.

```html live
<div class="demo-narrow">
  <ui-accordion type="multiple">
    <ui-accordion-item open>
      <ui-accordion-trigger>Shipping</ui-accordion-trigger>
      <ui-accordion-content>Orders ship within two working days.</ui-accordion-content>
    </ui-accordion-item>
    <ui-accordion-item open>
      <ui-accordion-trigger>Returns</ui-accordion-trigger>
      <ui-accordion-content>Return any item within 30 days of delivery.</ui-accordion-content>
    </ui-accordion-item>
    <ui-accordion-item>
      <ui-accordion-trigger>Warranty</ui-accordion-trigger>
      <ui-accordion-content>Every product has a two-year warranty.</ui-accordion-content>
    </ui-accordion-item>
  </ui-accordion>
</div>
```

### Disabled item

A `disabled` item cannot be opened or closed by the user. Its summary is dimmed.

```html live
<div class="demo-narrow">
  <ui-accordion>
    <ui-accordion-item>
      <ui-accordion-trigger>Account</ui-accordion-trigger>
      <ui-accordion-content>Manage your account details.</ui-accordion-content>
    </ui-accordion-item>
    <ui-accordion-item disabled>
      <ui-accordion-trigger>Billing (admins only)</ui-accordion-trigger>
      <ui-accordion-content>Billing settings.</ui-accordion-content>
    </ui-accordion-item>
    <ui-accordion-item>
      <ui-accordion-trigger>Notifications</ui-accordion-trigger>
      <ui-accordion-content>Choose which emails you receive.</ui-accordion-content>
    </ui-accordion-item>
  </ui-accordion>
</div>
```

### Rich trigger

The trigger takes any inline markup, such as a badge.

```html live
<div class="demo-narrow">
  <ui-accordion>
    <ui-accordion-item>
      <ui-accordion-trigger>Plan <ui-badge variant="secondary">Pro</ui-badge></ui-accordion-trigger>
      <ui-accordion-content>Your plan renews on the first of every month.</ui-accordion-content>
    </ui-accordion-item>
    <ui-accordion-item>
      <ui-accordion-trigger>Usage <ui-badge variant="outline">82%</ui-badge></ui-accordion-trigger>
      <ui-accordion-content>You have used 82% of this month's quota.</ui-accordion-content>
    </ui-accordion-item>
  </ui-accordion>
</div>
```

### Reacting to changes

Each item emits a bubbling `toggle` event when the user opens or closes it, and reflects its state to the `open`
attribute.

```html live
<custom-element name="accordion-events-demo">
  <script type="realm">
    const log = useState({ last: "Nothing toggled yet" });

    function toggled(event) {
      const item = event.target;
      log.last = `${item.dataset.name} is ${item.open ? "open" : "closed"}`;
    }
  </script>
  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      width: min(100%, calc(var(--spacing) * 96));
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>
  <ui-accordion type="multiple" ontoggle="toggled(event)">
    <ui-accordion-item data-name="General">
      <ui-accordion-trigger>General</ui-accordion-trigger>
      <ui-accordion-content>General settings.</ui-accordion-content>
    </ui-accordion-item>
    <ui-accordion-item data-name="Privacy">
      <ui-accordion-trigger>Privacy</ui-accordion-trigger>
      <ui-accordion-content>Privacy settings.</ui-accordion-content>
    </ui-accordion-item>
  </ui-accordion>
  <p><slot name="#log.last"></slot></p>
</custom-element>
<accordion-events-demo></accordion-events-demo>
```

## API

### Parts

| Element | Fills | Renders |
| --- | --- | --- |
| `ui-accordion` | | The container. Fills its container's width. |
| `ui-accordion-item` | the default slot of `ui-accordion` | A native `<details>` with a `<summary>` row and a chevron. |
| `ui-accordion-trigger` | the `<summary>` of its `ui-accordion-item` | The summary row's content. Accepts inline markup. |
| `ui-accordion-content` | the body of its `ui-accordion-item` | The content shown when the item is open, with bottom padding. |

### Attributes

#### ui-accordion

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"single"` \| `"multiple"` | `"single"` | In `single` mode, opening an item closes every other open item in the accordion. |

#### ui-accordion-item

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | boolean | `false` | Whether the item is open. Reflects. |
| `disabled` | boolean | `false` | Stops the user from opening or closing the item. Setting `open` from script still works. |

`ui-accordion-trigger` and `ui-accordion-content` have no attributes.

### Events

| Event | Element | Description |
| --- | --- | --- |
| `toggle` | `ui-accordion-item` | Fires when the user opens or closes the item. Bubbles. Read `event.target.open`. Setting `open` from script, including the automatic closing in `single` mode, does not fire it. |

### CSS parts

| Part | Element | Description |
| --- | --- | --- |
| `summary` | `ui-accordion-item` | The native `<summary>` row. |

### Accessibility

- Each item is a native `<details>`/`<summary>` pair, so the summary is announced as a button with its expanded
  state. The trigger's text is the button's name.
- Tab moves between summaries. Enter or Space opens or closes the focused item.
- A disabled item's summary stays focusable but does not toggle.
- Do not put links or buttons inside `ui-accordion-trigger`. The summary is already the button.


---

# Breadcrumb

Source: http://realm.js.org/components/breadcrumb/

`ui-breadcrumb` renders a `<nav>` landmark. Inside it, `ui-breadcrumb-list` renders the ordered list. Each step is a
`ui-breadcrumb-item` holding a `ui-breadcrumb-link` or, for the current page, a `ui-breadcrumb-page`. Put a
`ui-breadcrumb-separator` between items. It draws a chevron unless you give it other content.

```html live
<ui-breadcrumb>
  <ui-breadcrumb-list>
    <ui-breadcrumb-item><ui-breadcrumb-link href="#">Home</ui-breadcrumb-link></ui-breadcrumb-item>
    <ui-breadcrumb-separator></ui-breadcrumb-separator>
    <ui-breadcrumb-item><ui-breadcrumb-link href="#">Components</ui-breadcrumb-link></ui-breadcrumb-item>
    <ui-breadcrumb-separator></ui-breadcrumb-separator>
    <ui-breadcrumb-item><ui-breadcrumb-page>Breadcrumb</ui-breadcrumb-page></ui-breadcrumb-item>
  </ui-breadcrumb-list>
</ui-breadcrumb>
```

## Examples

### Custom separator

Content inside `ui-breadcrumb-separator` replaces the chevron.

```html live
<ui-breadcrumb>
  <ui-breadcrumb-list>
    <ui-breadcrumb-item><ui-breadcrumb-link href="#">Home</ui-breadcrumb-link></ui-breadcrumb-item>
    <ui-breadcrumb-separator>/</ui-breadcrumb-separator>
    <ui-breadcrumb-item><ui-breadcrumb-link href="#">Components</ui-breadcrumb-link></ui-breadcrumb-item>
    <ui-breadcrumb-separator>/</ui-breadcrumb-separator>
    <ui-breadcrumb-item><ui-breadcrumb-page>Breadcrumb</ui-breadcrumb-page></ui-breadcrumb-item>
  </ui-breadcrumb-list>
</ui-breadcrumb>
```

### Collapsed middle

Long trails can hide the middle steps. `ui-breadcrumb-ellipsis` draws three dots with a hidden "More" label. Put it
in a dropdown menu trigger to reveal the hidden pages.

```html live
<ui-breadcrumb>
  <ui-breadcrumb-list>
    <ui-breadcrumb-item><ui-breadcrumb-link href="#">Home</ui-breadcrumb-link></ui-breadcrumb-item>
    <ui-breadcrumb-separator></ui-breadcrumb-separator>
    <ui-breadcrumb-item>
      <ui-dropdown-menu>
        <ui-dropdown-menu-trigger>
          <ui-button variant="ghost" size="icon"><ui-breadcrumb-ellipsis>Show hidden pages</ui-breadcrumb-ellipsis></ui-button>
        </ui-dropdown-menu-trigger>
        <ui-dropdown-menu-content>
          <ui-menu-item value="docs">Documentation</ui-menu-item>
          <ui-menu-item value="guides">Guides</ui-menu-item>
        </ui-dropdown-menu-content>
      </ui-dropdown-menu>
    </ui-breadcrumb-item>
    <ui-breadcrumb-separator></ui-breadcrumb-separator>
    <ui-breadcrumb-item><ui-breadcrumb-link href="#">Components</ui-breadcrumb-link></ui-breadcrumb-item>
    <ui-breadcrumb-separator></ui-breadcrumb-separator>
    <ui-breadcrumb-item><ui-breadcrumb-page>Breadcrumb</ui-breadcrumb-page></ui-breadcrumb-item>
  </ui-breadcrumb-list>
</ui-breadcrumb>
```

### Custom label

The `<nav>` is labelled "Breadcrumb" by default. Change it with `label`, for example on a localized page.

```html live
<ui-breadcrumb label="Fil d'Ariane">
  <ui-breadcrumb-list>
    <ui-breadcrumb-item><ui-breadcrumb-link href="#">Accueil</ui-breadcrumb-link></ui-breadcrumb-item>
    <ui-breadcrumb-separator></ui-breadcrumb-separator>
    <ui-breadcrumb-item><ui-breadcrumb-page>Paramètres</ui-breadcrumb-page></ui-breadcrumb-item>
  </ui-breadcrumb-list>
</ui-breadcrumb>
```

### Bound to state

Inside a component, bind the current page with a value slot.

```html live
<custom-element name="breadcrumb-state-demo">
  <script type="realm">
    const view = useState({ title: "Overview" });

    function show(title) {
      view.title = title;
    }
  </script>
  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: center;
    }
  </style>
  <ui-breadcrumb>
    <ui-breadcrumb-list>
      <ui-breadcrumb-item><ui-breadcrumb-link href="#">Acme</ui-breadcrumb-link></ui-breadcrumb-item>
      <ui-breadcrumb-separator></ui-breadcrumb-separator>
      <ui-breadcrumb-item><ui-breadcrumb-page><slot name="#view.title"></slot></ui-breadcrumb-page></ui-breadcrumb-item>
    </ui-breadcrumb-list>
  </ui-breadcrumb>
  <ui-button-group>
    <ui-button variant="outline" size="sm" onclick="show('Overview')">Overview</ui-button>
    <ui-button variant="outline" size="sm" onclick="show('Invoices')">Invoices</ui-button>
  </ui-button-group>
</custom-element>
<breadcrumb-state-demo></breadcrumb-state-demo>
```

## API

### Parts

| Element | Fills | Renders |
| --- | --- | --- |
| `ui-breadcrumb` | | A `<nav>` landmark named by `label`. |
| `ui-breadcrumb-list` | the `<nav>` of `ui-breadcrumb` | An `<ol>` that lays out items and separators in a wrapping row of small muted text. |
| `ui-breadcrumb-item` | the `<ol>` of `ui-breadcrumb-list` | A list item (`role="listitem"`). |
| `ui-breadcrumb-link` | a `ui-breadcrumb-item` | An `<a>` that turns the foreground colour on hover. |
| `ui-breadcrumb-page` | a `ui-breadcrumb-item` | The current page: a `<span>` with `aria-current="page"` in the foreground colour. |
| `ui-breadcrumb-separator` | the `<ol>`, between items | A chevron, or its own content. Hidden from assistive technology. |
| `ui-breadcrumb-ellipsis` | a `ui-breadcrumb-item` or a button | Three dots with a visually hidden label (default "More"). |

### Attributes

#### ui-breadcrumb

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | string | `"Breadcrumb"` | Accessible name of the `<nav>` landmark. |

#### ui-breadcrumb-link

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | string | | Link target. |

The other parts have no attributes.

### Slots

| Slot | Element | Description |
| --- | --- | --- |
| (default) | `ui-breadcrumb-separator` | Replaces the chevron, for example with `/`. |
| (default) | `ui-breadcrumb-ellipsis` | The visually hidden label. Defaults to "More". |

### CSS parts

| Part | Element | Description |
| --- | --- | --- |
| `list` | `ui-breadcrumb-list` | The `<ol>`. |
| `link` | `ui-breadcrumb-link` | The `<a>`. |
| `page` | `ui-breadcrumb-page` | The `<span>` with `aria-current="page"`. |
| `label` | `ui-breadcrumb-ellipsis` | The visually hidden label. |

### Accessibility

- `ui-breadcrumb` is a `<nav>` landmark named by `label`, containing an `<ol>`.
- Each `ui-breadcrumb-item` has `role="listitem"`. Separators have `role="presentation"` and `aria-hidden`, so they
  are not announced.
- Links are reached with Tab. The current page has `aria-current="page"` and is not focusable.


---

# Collapsible

Source: http://realm.js.org/components/collapsible/

`ui-collapsible` wraps a native `<details>` element. Its `ui-collapsible-trigger` becomes the `<summary>`, and its
`ui-collapsible-content` is shown when it opens. The trigger lays out its content in a row with the ends pushed
apart, so a label and an icon need no extra markup. For a group of sections where only one is open at a time, use
[Accordion](/components/accordion/).

```html live
<div class="demo-narrow">
  <ui-collapsible>
    <ui-collapsible-trigger>
      3 starred repositories
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m7 15 5 5 5-5M7 9l5-5 5 5" /></svg>
    </ui-collapsible-trigger>
    <ui-collapsible-content>
      <ui-item variant="outline" size="sm">realm/core</ui-item>
      <ui-item variant="outline" size="sm">realm/ui</ui-item>
      <ui-item variant="outline" size="sm">realm/site</ui-item>
    </ui-collapsible-content>
  </ui-collapsible>
</div>
```

## Examples

### Open by default

Add `open` to start expanded. The attribute reflects, so it also tracks the current state.

```html live
<div class="demo-narrow">
  <ui-collapsible open>
    <ui-collapsible-trigger>Release notes</ui-collapsible-trigger>
    <ui-collapsible-content>
      <p class="demo-muted">Faster startup, smaller bundle and a new sidebar.</p>
    </ui-collapsible-content>
  </ui-collapsible>
</div>
```

### Disabled

`disabled` stops the user from toggling it. The trigger is dimmed.

```html live
<div class="demo-narrow">
  <ui-collapsible disabled>
    <ui-collapsible-trigger>Advanced options (locked)</ui-collapsible-trigger>
    <ui-collapsible-content>Only administrators can change these.</ui-collapsible-content>
  </ui-collapsible>
</div>
```

### Controlled from state

Bind `open` with `_open` and listen for `toggle` to keep state in sync.

```html live
<custom-element name="collapsible-state-demo">
  <script type="realm">
    const panel = useState({ open: false });

    function toggled(event) {
      panel.open = event.target.open;
    }

    function flip() {
      panel.open = !panel.open;
    }
  </script>
  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      width: min(100%, calc(var(--spacing) * 80));
    }
  </style>
  <ui-button variant="outline" size="sm" onclick="flip()">Toggle from outside</ui-button>
  <ui-collapsible _open="#panel.open" ontoggle="toggled(event)">
    <ui-collapsible-trigger>Filters</ui-collapsible-trigger>
    <ui-collapsible-content>Status, owner and date range.</ui-collapsible-content>
  </ui-collapsible>
</custom-element>
<collapsible-state-demo></collapsible-state-demo>
```

## API

### Parts

| Element | Fills | Renders |
| --- | --- | --- |
| `ui-collapsible` | | A native `<details>`. Fills its container's width. |
| `ui-collapsible-trigger` | the `<summary>` of `ui-collapsible` | A row with its content spread to both ends, in small semibold text. Icons are sized to `calc(var(--spacing) * 4)`. |
| `ui-collapsible-content` | the body of `ui-collapsible` | A column with `calc(var(--spacing) * 2)` gaps, shown when open. |

### Attributes

#### ui-collapsible

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | boolean | `false` | Whether the content is shown. Reflects. |
| `disabled` | boolean | `false` | Stops the user from toggling. Setting `open` from script still works. |

`ui-collapsible-trigger` and `ui-collapsible-content` have no attributes.

### Events

| Event | Element | Description |
| --- | --- | --- |
| `toggle` | `ui-collapsible` | Fires when the user opens or closes it. Bubbles. Read `event.target.open`. Not fired when `open` is set from script. |

### CSS parts

| Part | Element | Description |
| --- | --- | --- |
| `trigger` | `ui-collapsible` | The native `<summary>`. |

### Accessibility

- The trigger is a native `<summary>`, announced as a button with its expanded state.
- Tab focuses the trigger. Enter or Space toggles it.
- Do not put other interactive elements in the trigger. The summary is already the button.


---

# Menubar

Source: http://realm.js.org/components/menubar/

`ui-menubar` is a bordered horizontal bar with `role="menubar"`. Each `ui-menubar-menu` in it pairs a
`ui-menubar-trigger`, a small button with `role="menuitem"`, with a `ui-menubar-content`, a `popover="auto"` menu
anchored under the trigger. The entries are the same `ui-menu-*` parts as in [Dropdown Menu](/components/dropdown-menu/).
The bar declares a `focusgroup`, so Left and Right arrows move between the triggers.

```html live
<ui-menubar>
  <ui-menubar-menu>
    <ui-menubar-trigger>File</ui-menubar-trigger>
    <ui-menubar-content>
      <ui-menu-item value="new-tab">New Tab <ui-menu-shortcut>⌘T</ui-menu-shortcut></ui-menu-item>
      <ui-menu-item value="new-window">New Window <ui-menu-shortcut>⌘N</ui-menu-shortcut></ui-menu-item>
      <ui-menu-separator></ui-menu-separator>
      <ui-menu-item value="print">Print… <ui-menu-shortcut>⌘P</ui-menu-shortcut></ui-menu-item>
    </ui-menubar-content>
  </ui-menubar-menu>
  <ui-menubar-menu>
    <ui-menubar-trigger>Edit</ui-menubar-trigger>
    <ui-menubar-content>
      <ui-menu-item value="undo">Undo <ui-menu-shortcut>⌘Z</ui-menu-shortcut></ui-menu-item>
      <ui-menu-item value="redo">Redo <ui-menu-shortcut>⇧⌘Z</ui-menu-shortcut></ui-menu-item>
      <ui-menu-separator></ui-menu-separator>
      <ui-menu-item value="cut">Cut</ui-menu-item>
      <ui-menu-item value="copy">Copy</ui-menu-item>
      <ui-menu-item value="paste" disabled>Paste</ui-menu-item>
    </ui-menubar-content>
  </ui-menubar-menu>
  <ui-menubar-menu>
    <ui-menubar-trigger>View</ui-menubar-trigger>
    <ui-menubar-content>
      <ui-menu-checkbox-item value="bookmarks" checked>Always Show Bookmarks Bar</ui-menu-checkbox-item>
      <ui-menu-separator></ui-menu-separator>
      <ui-menu-item value="reload">Reload <ui-menu-shortcut>⌘R</ui-menu-shortcut></ui-menu-item>
      <ui-menu-item value="fullscreen">Toggle Fullscreen</ui-menu-item>
    </ui-menubar-content>
  </ui-menubar-menu>
</ui-menubar>
```

## Examples

### Handling commands

Every item emits a bubbling `select` event with `{ value }` in `detail`, and its menu closes. Listen once on the
menubar to handle every menu.

```html live
<custom-element name="menubar-commands-demo">
  <script type="realm">
    const log = useState({ last: "none" });

    function run(event) {
      log.last = event.detail.value;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: center;
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>

  <ui-menubar onselect="run(event)">
    <ui-menubar-menu>
      <ui-menubar-trigger>File</ui-menubar-trigger>
      <ui-menubar-content>
        <ui-menu-item value="open">Open…</ui-menu-item>
        <ui-menu-item value="save">Save</ui-menu-item>
      </ui-menubar-content>
    </ui-menubar-menu>
    <ui-menubar-menu>
      <ui-menubar-trigger>Profiles</ui-menubar-trigger>
      <ui-menubar-content>
        <ui-menu-radio-group value="benoit">
          <ui-menu-radio-item value="andy">Andy</ui-menu-radio-item>
          <ui-menu-radio-item value="benoit">Benoit</ui-menu-radio-item>
        </ui-menu-radio-group>
        <ui-menu-separator></ui-menu-separator>
        <ui-menu-item value="remove" variant="destructive">Remove profile</ui-menu-item>
      </ui-menubar-content>
    </ui-menubar-menu>
  </ui-menubar>
  <p>Last command: <slot name="#log.last"></slot></p>
</custom-element>
<menubar-commands-demo></menubar-commands-demo>
```

### Toolbar of buttons

A menubar can also hold plain buttons. Left and Right arrows move focus between them and wrap at the ends.

```html live
<ui-menubar>
  <ui-button variant="ghost" size="sm">Bold</ui-button>
  <ui-button variant="ghost" size="sm">Italic</ui-button>
  <ui-button variant="ghost" size="sm">Underline</ui-button>
</ui-menubar>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-menubar` | | The bordered bar, `role="menubar"`, with a gap between menus. |
| `ui-menubar-menu` | (default) | One menu: its trigger and content, with no box of its own. |
| `ui-menubar-trigger` | (default) | A `<button>` with `role="menuitem"` and `aria-haspopup="menu"` in `var(--text-sm)` medium. A click toggles its menu. |
| `ui-menubar-content` | (default) | A bordered `popover="auto"` panel with `role="menu"`, anchored under the trigger. |
| `ui-menu-*` | (default) | Items, labels, groups, separators and shortcuts. See [Dropdown Menu](/components/dropdown-menu/). |

None of the menubar parts has attributes of its own. See [Dropdown Menu](/components/dropdown-menu/) for the item
attributes and the `select` event.

### CSS parts

| Element | Part | Description |
| --- | --- | --- |
| `ui-menubar` | `bar` | The focusgroup wrapper around the slot. It uses `display: contents`, so it does not affect layout. |
| `ui-menubar-trigger` | `trigger` | The `<button>`. |
| `ui-menubar-content` | `menu` | The focusgroup wrapper around the items. |

### Accessibility

- The bar has `role="menubar"`, each trigger is a `<button>` with `role="menuitem"` and `aria-haspopup="menu"`, and
  each content has `role="menu"`.
- Left and Right arrows move between triggers and wrap (`focusgroup="menubar inline wrap"`). Enter or Space on a
  trigger opens its menu and focuses the first enabled item.
- Inside an open menu, Up and Down arrows move between items and wrap, Home and End jump to the first and last item,
  Enter or Space selects, and Escape closes the menu and returns focus to the trigger. A click outside also closes it.


---

# Navigation Menu

Source: http://realm.js.org/components/navigation-menu/

`ui-navigation-menu` renders a `<nav>` landmark around a `ui-navigation-menu-list`. Each `ui-navigation-menu-item`
holds either a `ui-navigation-menu-link`, or a `ui-navigation-menu-trigger` with a `ui-navigation-menu-content`. The
content goes in a native `popover="auto"` panel anchored below the trigger. Panels open on click and after a short
hover delay, and close when the pointer leaves, on Escape or on a click outside.

```html live
<ui-navigation-menu>
  <ui-navigation-menu-list>
    <ui-navigation-menu-item>
      <ui-navigation-menu-trigger>Getting started</ui-navigation-menu-trigger>
      <ui-navigation-menu-content width="72">
        <ui-navigation-menu-link href="#">
          <strong>Introduction</strong>
          <span>What REALM is and how it works.</span>
        </ui-navigation-menu-link>
        <ui-navigation-menu-link href="#">
          <strong>Installation</strong>
          <span>Add REALM to a page or a build.</span>
        </ui-navigation-menu-link>
      </ui-navigation-menu-content>
    </ui-navigation-menu-item>
    <ui-navigation-menu-item>
      <ui-navigation-menu-trigger>Components</ui-navigation-menu-trigger>
      <ui-navigation-menu-content width="80" columns="2">
        <ui-navigation-menu-link href="#">Alert Dialog</ui-navigation-menu-link>
        <ui-navigation-menu-link href="#">Hover Card</ui-navigation-menu-link>
        <ui-navigation-menu-link href="#">Progress</ui-navigation-menu-link>
        <ui-navigation-menu-link href="#">Tabs</ui-navigation-menu-link>
      </ui-navigation-menu-content>
    </ui-navigation-menu-item>
    <ui-navigation-menu-item>
      <ui-navigation-menu-link href="#" current>Docs</ui-navigation-menu-link>
    </ui-navigation-menu-item>
  </ui-navigation-menu-list>
</ui-navigation-menu>
```

## Examples

### Links only

Use only links for a flat bar. Mark the active one with `current`.

```html live
<ui-navigation-menu label="Account">
  <ui-navigation-menu-list>
    <ui-navigation-menu-item><ui-navigation-menu-link href="#" current>Profile</ui-navigation-menu-link></ui-navigation-menu-item>
    <ui-navigation-menu-item><ui-navigation-menu-link href="#">Billing</ui-navigation-menu-link></ui-navigation-menu-item>
    <ui-navigation-menu-item><ui-navigation-menu-link href="#">Team</ui-navigation-menu-link></ui-navigation-menu-item>
  </ui-navigation-menu-list>
</ui-navigation-menu>
```

### Simple list

Without `width` or `columns`, the content is a single column at least `calc(var(--spacing) * 64)` wide.

```html live
<ui-navigation-menu>
  <ui-navigation-menu-list>
    <ui-navigation-menu-item>
      <ui-navigation-menu-trigger>Resources</ui-navigation-menu-trigger>
      <ui-navigation-menu-content>
        <ui-navigation-menu-link href="#">Blog</ui-navigation-menu-link>
        <ui-navigation-menu-link href="#">Changelog</ui-navigation-menu-link>
      </ui-navigation-menu-content>
    </ui-navigation-menu-item>
    <ui-navigation-menu-item><ui-navigation-menu-link href="#">Pricing</ui-navigation-menu-link></ui-navigation-menu-item>
  </ui-navigation-menu-list>
</ui-navigation-menu>
```

## API

### Parts

| Element | Fills | Renders |
| --- | --- | --- |
| `ui-navigation-menu` | | A `<nav>` landmark named by `label`. |
| `ui-navigation-menu-list` | the `<nav>` of `ui-navigation-menu` | A `<ul>` laying out the items in a row, with arrow-key navigation. |
| `ui-navigation-menu-item` | the `<ul>` of `ui-navigation-menu-list` | A list item (`role="listitem"`) and, when it has content, the popover panel. |
| `ui-navigation-menu-trigger` | a `ui-navigation-menu-item` | A `<button>` with a chevron and `aria-expanded` that opens the item's panel. |
| `ui-navigation-menu-content` | the popover panel of its `ui-navigation-menu-item` | A grid of links inside the panel. |
| `ui-navigation-menu-link` | a `ui-navigation-menu-item` or a `ui-navigation-menu-content` | An `<a>`. At the top level it looks like a trigger. Inside content it is a block row, where a first child is the title and a last child the muted description. |

### Attributes

#### ui-navigation-menu

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | string | `"Main"` | Accessible name of the `<nav>` landmark. |

#### ui-navigation-menu-content

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | number | | Width of the content in spacing units, so `width="72"` is `calc(var(--spacing) * 72)`. |
| `columns` | number | `1` | Number of equal grid columns for the links. |

#### ui-navigation-menu-link

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | string | | Link target. |
| `current` | boolean | `false` | Highlights the link and sets `aria-current="page"`. |

`ui-navigation-menu-list`, `ui-navigation-menu-item` and `ui-navigation-menu-trigger` have no attributes.

### CSS parts

| Part | Element | Description |
| --- | --- | --- |
| `list` | `ui-navigation-menu-list` | The `<ul>`. |
| `panel` | `ui-navigation-menu-item` | The popover panel around the content. |
| `trigger` | `ui-navigation-menu-trigger` | The `<button>`. |
| `link` | `ui-navigation-menu-link` | The `<a>`. |

### Accessibility

- `ui-navigation-menu` is a `<nav>` landmark named by `label`. Each `ui-navigation-menu-item` has `role="listitem"`.
- Links are native `<a>` elements. Triggers are native `<button>` elements with `aria-expanded`. Enter or Space
  opens and closes the panel.
- With the panel open, Tab moves into the panel's links. Escape closes the panel and, when focus was inside it,
  returns focus to the trigger.
- Hover opens a panel after 150 ms and closes it 200 ms after the pointer leaves both the trigger and the panel,
  so moving the pointer from trigger to panel does not close it.
- The list declares `focusgroup="toolbar inline"`, so Left and Right arrows move between the top-level items.


---

# Pagination

Source: http://realm.js.org/components/pagination/

`ui-pagination` renders a `<nav>` with Previous, Next and numbered page controls from two numbers: the current
`page` and the `total` number of pages. It always shows the first and last page, the pages within `siblings` of the
current one, and an ellipsis for each gap. It works in two modes:

- Without `href`, Previous, Next and the page numbers are native buttons. Clicking one (or pressing Enter or Space)
  updates the `page` attribute in place and fires `change`. Use this for client-side lists.
- With `href`, Previous, Next and every page number are links built from the pattern, for example
  `?page={page}`.

```html live
<ui-pagination page="5" total="10"></ui-pagination>
```

## Examples

### Siblings

`siblings` sets how many pages are shown on each side of the current page. The default is `1`.

```html live
<div class="demo-stack">
  <ui-pagination page="10" total="20" siblings="0"></ui-pagination>
  <ui-pagination page="10" total="20"></ui-pagination>
  <ui-pagination page="10" total="20" siblings="2"></ui-pagination>
</div>
```

### Few pages

When every page fits, no ellipsis is shown. Previous is disabled on the first page and Next on the last.

```html live
<ui-pagination page="1" total="3"></ui-pagination>
```

### Links

With `href`, `{page}` in the pattern is replaced by each page number, so the numbers are crawlable links and work
without script. The component does not change `page` itself in this mode. The next page load sets it.

```html
<ui-pagination page="2" total="5" href="/invoices?page={page}"></ui-pagination>
```

### Controlled from state

Bind `page` and `total` from state and read the new page from `event.detail.page`. Call `event.preventDefault()`
on `change` to cancel the move, for example while data is still loading.

```html live
<custom-element name="pagination-state-demo">
  <script type="realm">
    const list = useState({
      page: 1,
      total: 12,
      get range() {
        const start = (this.page - 1) * 10 + 1;
        return `Showing ${start} to ${start + 9} of 120 invoices`;
      },
    });

    function paged(event) {
      list.page = event.detail.page;
    }
  </script>
  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: center;
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>
  <p><slot name="#list.range"></slot></p>
  <ui-pagination _page="#list.page" _total="#list.total" onchange="paged(event)"></ui-pagination>
</custom-element>
<pagination-state-demo></pagination-state-demo>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `page` | number | `1` | The current page. Integer, at least 1. Updated by the component when `href` is not set. |
| `total` | number | `1` | Number of pages. Integer, at least 1. |
| `siblings` | number | `1` | Pages shown on each side of the current page. Integer, at least 0. |
| `href` | string | | URL pattern for page links. `{page}` is replaced by the page number. When not set, the controls are buttons that update `page`. |
| `label` | string | `"Pagination"` | Accessible name of the `<nav>` landmark. |

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `change` | `{ page: number }` | Fires before the page changes, from Previous, Next or a page number. Bubbles and is cancelable. `preventDefault()` keeps the current page and, in `href` mode, stops the link from navigating. Not fired for the current page or a page out of range. |

### CSS parts

| Part | Description |
| --- | --- |
| `list` | The `<ul>` that lays out the controls. |
| `previous` | The Previous control: a `<button>`, or an `<a>` in `href` mode. |
| `next` | The Next control: a `<button>`, or an `<a>` in `href` mode. |
| `page` | Each page number: a `<button>`, or an `<a>` in `href` mode. The current one has `aria-current="page"`. |

### Accessibility

- The component is a `<nav>` landmark named by `label`, containing a list.
- The current page has `aria-current="page"`. Ellipses are hidden from assistive technology.
- Without `href` every control is a native `<button>` that Tab reaches and Enter or Space activates. Previous and
  Next are `disabled` at the first and last page.
- In `href` mode every control is a link reached with Tab. At the first and last page, Previous and Next have no
  `href` and `aria-disabled="true"`.


---

# Sidebar

Source: http://realm.js.org/components/sidebar/

The sidebar is a set of parts that build an application shell:

- `ui-sidebar-layout` places the `ui-sidebar` next to a `ui-sidebar-inset`, collapses the sidebar to an icon rail,
  and turns it into an off-canvas drawer on screens narrower than 768px.
- `ui-sidebar` is the panel itself. `ui-sidebar-header` and `ui-sidebar-footer` stick to its ends and
  `ui-sidebar-content` scrolls between them.
- `ui-sidebar-group` groups a `ui-sidebar-group-label` and a `ui-sidebar-menu`.
- `ui-sidebar-menu` is a list of `ui-sidebar-menu-item` elements, each holding a `ui-sidebar-menu-button` and an
  optional `ui-sidebar-menu-badge`.
- `ui-sidebar-trigger` is the button that collapses or opens the sidebar.
- `ui-sidebar-inset` is the main content area.

The layout is designed to fill the viewport (`min-height: 100dvh`). The demos on this page are placed in a box with
a fixed height. The `ui-sidebar-layout::part(sidebar)` rule shown in the code makes the sidebar follow that box
instead of the viewport.

```html live
<style>
  .sidebar-demo {
    width: min(calc(var(--spacing) * 160), calc(100vw - var(--spacing) * 28));
    height: calc(var(--spacing) * 96);
    overflow: hidden;
    contain: layout paint;
    border: 1px solid var(--border);
    border-radius: var(--radius-lg);
  }
  .sidebar-demo ui-sidebar-layout {
    height: 100%;
    min-height: 0;
  }
  .sidebar-demo ui-sidebar-layout::part(sidebar) {
    height: 100%;
  }
  .sidebar-demo header {
    display: flex;
    align-items: center;
    gap: calc(var(--spacing) * 2);
    padding: calc(var(--spacing) * 2) calc(var(--spacing) * 3);
    border-bottom: 1px solid var(--border);
    font-size: var(--text-sm);
    font-weight: var(--font-weight-medium);
  }
  .sidebar-demo .brand {
    display: flex;
    align-items: center;
    gap: calc(var(--spacing) * 2);
    font-size: var(--text-sm);
    font-weight: var(--font-weight-semibold);
    white-space: nowrap;
    overflow: hidden;
  }
  .sidebar-demo .logo {
    display: grid;
    place-items: center;
    flex-shrink: 0;
    width: calc(var(--spacing) * 8);
    height: calc(var(--spacing) * 8);
    border-radius: var(--radius-md);
    background: var(--primary);
    color: var(--primary-foreground);
  }
  .sidebar-demo .body {
    padding: calc(var(--spacing) * 4);
    font-size: var(--text-sm);
    color: var(--muted-foreground);
  }
</style>
<div class="sidebar-demo">
  <ui-sidebar-layout>
    <ui-sidebar>
      <ui-sidebar-header>
        <div class="brand"><span class="logo">A</span><span>Acme Inc</span></div>
      </ui-sidebar-header>
      <ui-sidebar-content>
        <ui-sidebar-group>
          <ui-sidebar-group-label>Platform</ui-sidebar-group-label>
          <ui-sidebar-menu>
            <ui-sidebar-menu-item>
              <ui-sidebar-menu-button href="#dashboard" current label="Dashboard">
                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M3 10.5 12 3l9 7.5V21H3z" /></svg>
                Dashboard
              </ui-sidebar-menu-button>
            </ui-sidebar-menu-item>
            <ui-sidebar-menu-item>
              <ui-sidebar-menu-button href="#inbox" label="Inbox">
                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M22 12h-6l-2 3h-4l-2-3H2M5.5 5h13L22 12v7H2v-7z" /></svg>
                Inbox
              </ui-sidebar-menu-button>
              <ui-sidebar-menu-badge>12</ui-sidebar-menu-badge>
            </ui-sidebar-menu-item>
            <ui-sidebar-menu-item>
              <ui-sidebar-menu-button href="#calendar" label="Calendar">
                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><rect x="3" y="4" width="18" height="17" rx="2" /><path d="M3 10h18M8 2v4M16 2v4" /></svg>
                Calendar
              </ui-sidebar-menu-button>
            </ui-sidebar-menu-item>
          </ui-sidebar-menu>
        </ui-sidebar-group>
        <ui-sidebar-group>
          <ui-sidebar-group-label>Settings</ui-sidebar-group-label>
          <ui-sidebar-menu>
            <ui-sidebar-menu-item>
              <ui-sidebar-menu-button href="#team" label="Team">
                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><circle cx="9" cy="8" r="4" /><path d="M2 21a7 7 0 0 1 14 0M16 4a4 4 0 0 1 0 8M22 21a7 7 0 0 0-4-6.3" /></svg>
                Team
              </ui-sidebar-menu-button>
            </ui-sidebar-menu-item>
            <ui-sidebar-menu-item>
              <ui-sidebar-menu-button href="#billing" label="Billing">
                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><rect x="2" y="5" width="20" height="14" rx="2" /><path d="M2 10h20" /></svg>
                Billing
              </ui-sidebar-menu-button>
            </ui-sidebar-menu-item>
          </ui-sidebar-menu>
        </ui-sidebar-group>
      </ui-sidebar-content>
      <ui-sidebar-footer>
        <ui-dropdown-menu>
          <ui-dropdown-menu-trigger>
            <ui-button variant="ghost" size="sm"><ui-avatar><ui-avatar-fallback>JD</ui-avatar-fallback></ui-avatar> Jane Doe</ui-button>
          </ui-dropdown-menu-trigger>
          <ui-dropdown-menu-content placement="top-start">
            <ui-menu-item value="profile">Profile</ui-menu-item>
            <ui-menu-item value="logout" variant="destructive">Log out</ui-menu-item>
          </ui-dropdown-menu-content>
        </ui-dropdown-menu>
      </ui-sidebar-footer>
    </ui-sidebar>
    <ui-sidebar-inset>
      <header>
        <ui-sidebar-trigger></ui-sidebar-trigger>
        Dashboard
      </header>
      <div class="body">Press the trigger, or Ctrl+B (⌘B on macOS), to collapse the sidebar to icons.</div>
    </ui-sidebar-inset>
  </ui-sidebar-layout>
</div>
```

## Examples

### Collapsed by default

Add `collapsed` to start with the icon rail. Menu buttons shrink to their icon, and labels and badges are hidden.
The `label` attribute of each menu button becomes its tooltip (`title`). `collapsed` reflects, so you can style or
read the current state.

```html live
<div class="sidebar-demo">
  <ui-sidebar-layout collapsed>
    <ui-sidebar>
      <ui-sidebar-header>
        <div class="brand"><span class="logo">A</span><span>Acme Inc</span></div>
      </ui-sidebar-header>
      <ui-sidebar-content>
        <ui-sidebar-group>
          <ui-sidebar-group-label>Platform</ui-sidebar-group-label>
          <ui-sidebar-menu>
            <ui-sidebar-menu-item>
              <ui-sidebar-menu-button href="#dashboard" current label="Dashboard">
                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M3 10.5 12 3l9 7.5V21H3z" /></svg>
                Dashboard
              </ui-sidebar-menu-button>
            </ui-sidebar-menu-item>
            <ui-sidebar-menu-item>
              <ui-sidebar-menu-button href="#inbox" label="Inbox">
                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M22 12h-6l-2 3h-4l-2-3H2M5.5 5h13L22 12v7H2v-7z" /></svg>
                Inbox
              </ui-sidebar-menu-button>
              <ui-sidebar-menu-badge>12</ui-sidebar-menu-badge>
            </ui-sidebar-menu-item>
          </ui-sidebar-menu>
        </ui-sidebar-group>
      </ui-sidebar-content>
    </ui-sidebar>
    <ui-sidebar-inset>
      <header>
        <ui-sidebar-trigger></ui-sidebar-trigger>
        Overview
      </header>
      <div class="body">The sidebar starts collapsed.</div>
    </ui-sidebar-inset>
  </ui-sidebar-layout>
</div>
```

### Handling navigation

Each menu button fires a bubbling, cancelable `select` event when clicked, and its link then navigates as usual
unless a listener calls `preventDefault()`. Listen once on `ui-sidebar` and keep the current item in state. Hash
links like `#projects` keep the page in place. This is how the [dashboard example](/examples/dashboard/) switches
views without reloading.

```html live
<custom-element name="sidebar-select-demo">
  <script type="realm">
    const view = useState({
      page: "home",
      get items() {
        return [
          { id: "home", href: "#home", label: "Home", current: this.page === "home" },
          { id: "projects", href: "#projects", label: "Projects", current: this.page === "projects" },
          { id: "reports", href: "#reports", label: "Reports", current: this.page === "reports" },
        ];
      },
    });

    function pick(event) {
      view.page = event.target.dataset.id;
    }
  </script>
  <style type="realm">
    :host {
      display: block;
      width: min(calc(var(--spacing) * 160), calc(100vw - var(--spacing) * 28));
      height: calc(var(--spacing) * 64);
      overflow: hidden;
      contain: layout paint;
      border: 1px solid var(--border);
      border-radius: var(--radius-lg);
    }
    ui-sidebar-layout {
      height: 100%;
      min-height: 0;
    }
    ui-sidebar-layout::part(sidebar) {
      height: 100%;
    }
    p {
      margin: 0;
      padding: calc(var(--spacing) * 4);
      font-size: var(--text-sm);
    }
  </style>
  <ui-sidebar-layout>
    <ui-sidebar onselect="pick(event)">
      <ui-sidebar-content>
        <ui-sidebar-group>
          <ui-sidebar-group-label>Workspace</ui-sidebar-group-label>
          <ui-sidebar-menu>
            <ui-sidebar-menu-item repeat="#view.items" as="item" key="id">
              <ui-sidebar-menu-button _href="#item.href" _current="#item.current" _label="#item.label" _data-id="#item.id">
                <slot name="#item.label"></slot>
              </ui-sidebar-menu-button>
            </ui-sidebar-menu-item>
          </ui-sidebar-menu>
        </ui-sidebar-group>
      </ui-sidebar-content>
    </ui-sidebar>
    <ui-sidebar-inset>
      <p>Current page: <slot name="#view.page"></slot></p>
    </ui-sidebar-inset>
  </ui-sidebar-layout>
</custom-element>
<sidebar-select-demo></sidebar-select-demo>
```

### Remembering the state

Set `persist` to a `localStorage` key. The layout saves `collapsed` under that key on every change and restores it
on the next page load.

```html
<ui-sidebar-layout persist="app-sidebar">
  …
</ui-sidebar-layout>
```

## API

### Parts

| Element | Fills | Renders |
| --- | --- | --- |
| `ui-sidebar-layout` | | The shell, with an `<aside>` for the sidebar, the inset beside it, and a backdrop on small screens. |
| `ui-sidebar` | the `<aside>` of `ui-sidebar-layout` | The panel, a full-height column. |
| `ui-sidebar-header` | the top of `ui-sidebar` | A padded column for a logo or team switcher. |
| `ui-sidebar-content` | the middle of `ui-sidebar` | A scrolling `<nav>` around the groups. |
| `ui-sidebar-footer` | the bottom of `ui-sidebar` | A padded column for a user menu. |
| `ui-sidebar-group` | `ui-sidebar-content` | A `role="group"` section, named by its label. |
| `ui-sidebar-group-label` | `ui-sidebar-group` | The small muted heading. Hidden when collapsed. |
| `ui-sidebar-menu` | `ui-sidebar-group` | A `<ul>` of menu items with Up and Down arrow navigation. |
| `ui-sidebar-menu-item` | the `<ul>` of `ui-sidebar-menu` | A list item (`role="listitem"`). |
| `ui-sidebar-menu-button` | `ui-sidebar-menu-item` | The item's `<a>`, with icon and text. Icons are sized to `calc(var(--spacing) * 4)`. When collapsed, only the icon shows. |
| `ui-sidebar-menu-badge` | `ui-sidebar-menu-item` | Short text, such as a count, at the end of the item. Hidden when collapsed. |
| `ui-sidebar-trigger` | anywhere inside `ui-sidebar-layout` | A ghost icon `ui-button` labelled "Toggle sidebar". |
| `ui-sidebar-inset` | the main area of `ui-sidebar-layout` | A `<main>` panel with rounded corners next to the sidebar. |

### Attributes

#### ui-sidebar-layout

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `collapsed` | boolean | `false` | Collapses the sidebar to an icon rail (`calc(var(--spacing) * 12)` wide) and hides labels, badges and group labels. Reflects. Ignored on small screens, where the sidebar is off-canvas instead. |
| `persist` | string | | A `localStorage` key. When set, `collapsed` is restored from it on connect and saved to it on every change. |

#### ui-sidebar-menu-button

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | string | | Link target. Without it, the item is a button activated by Enter and Space. |
| `current` | boolean | `false` | Marks the current page with a highlight, medium weight and `aria-current="page"` on the link. |
| `label` | string | | Sets the link's `title`, which is the tooltip when the sidebar is collapsed. |

The other parts have no attributes.

### Properties and methods

| Member | Element | Description |
| --- | --- | --- |
| `toggle()` | `ui-sidebar-layout` | On wide screens, flips `collapsed`. On small screens, opens or closes the off-canvas sidebar. |

### Events

| Event | Element | Description |
| --- | --- | --- |
| `select` | `ui-sidebar-menu-button` | Fires when the button is clicked. Bubbles and is cancelable. `preventDefault()` stops the link from following its `href`. |
| `sidebartoggle` | `ui-sidebar-trigger` | Fires when the trigger is clicked. Bubbles to the enclosing `ui-sidebar-layout`, which calls `toggle()`. |

### CSS parts

| Part | Element | Description |
| --- | --- | --- |
| `sidebar` | `ui-sidebar-layout` | The `<aside>` holding the sidebar. Sticky and `100dvh` tall by default. |
| `backdrop` | `ui-sidebar-layout` | The overlay behind the off-canvas sidebar on small screens. Clicking it closes the sidebar. |
| `content` | `ui-sidebar-content` | The scrolling `<nav>`. |
| `menu` | `ui-sidebar-menu` | The `<ul>`. |
| `button` | `ui-sidebar-menu-button` | The `<a>`. |
| `main` | `ui-sidebar-inset` | The `<main>` panel. |

### CSS states and custom properties

- `ui-sidebar-layout:state(attr-collapsed)` matches while collapsed (the same as `[collapsed]`).
- `ui-sidebar-layout:state(state-layout-mobile)` matches when the viewport is narrower than 768px, and
  `:state(state-layout-open)` while the off-canvas sidebar is open.
- The layout sets `--ui-sidebar-width` and `--ui-sidebar-label` (`block` or `none`) for its descendants. Group
  labels and badges use `--ui-sidebar-label` to hide when collapsed.

### Accessibility

- The layout renders an `<aside>` for the sidebar, `ui-sidebar-inset` renders a `<main>`, and
  `ui-sidebar-content` renders a `<nav>`.
- Each group has `role="group"` and is labelled by its `ui-sidebar-group-label`. Each menu is a list, each menu item
  a list item with a native link inside. The current item's link has `aria-current`.
- The trigger is a `ui-button` labelled "Toggle sidebar".
- Ctrl+B, or ⌘B on macOS, toggles every `ui-sidebar-layout` on the page from anywhere in the document.
- Each menu declares `focusgroup="menu block"`, so Up and Down arrows move between its items.


---

# Tabs

Source: http://realm.js.org/components/tabs/

`ui-tabs` holds a `ui-tabs-list` of `ui-tabs-trigger` buttons and one `ui-tabs-content` panel per trigger. A trigger
and a panel belong together when they share a `value`. Only the selected panel is visible. The others get the
`hidden` attribute. The tabs follow the ARIA tabs pattern with automatic activation, so moving focus with the arrow
keys also selects the tab.

The tabs fill the width of their container. The list itself is as wide as its triggers.

```html live
<div class="demo-narrow">
  <ui-tabs value="account">
    <ui-tabs-list>
      <ui-tabs-trigger value="account">Account</ui-tabs-trigger>
      <ui-tabs-trigger value="password">Password</ui-tabs-trigger>
    </ui-tabs-list>
    <ui-tabs-content value="account">
      <ui-card>
        <ui-card-header>
          <ui-card-title>Account</ui-card-title>
          <ui-card-description>Make changes to your account here.</ui-card-description>
        </ui-card-header>
        <ui-card-content>
          <ui-field><ui-label for="tabs-name">Name</ui-label><ui-input id="tabs-name" value="Pedro Duarte"></ui-input></ui-field>
        </ui-card-content>
      </ui-card>
    </ui-tabs-content>
    <ui-tabs-content value="password">
      <ui-card>
        <ui-card-header>
          <ui-card-title>Password</ui-card-title>
          <ui-card-description>Change your password here.</ui-card-description>
        </ui-card-header>
        <ui-card-content>
          <ui-field><ui-label for="tabs-password">Current password</ui-label><ui-input id="tabs-password" type="password"></ui-input></ui-field>
        </ui-card-content>
      </ui-card>
    </ui-tabs-content>
  </ui-tabs>
</div>
```

## Examples

### Disabled tab

A `disabled` trigger is dimmed, cannot be selected and is skipped by the arrow keys.

```html live
<div class="demo-narrow">
  <ui-tabs value="overview">
    <ui-tabs-list>
      <ui-tabs-trigger value="overview">Overview</ui-tabs-trigger>
      <ui-tabs-trigger value="analytics">Analytics</ui-tabs-trigger>
      <ui-tabs-trigger value="reports" disabled>Reports</ui-tabs-trigger>
    </ui-tabs-list>
    <ui-tabs-content value="overview"><p class="demo-text">Revenue is up 12% this month.</p></ui-tabs-content>
    <ui-tabs-content value="analytics"><p class="demo-text">Visitors by country and device.</p></ui-tabs-content>
    <ui-tabs-content value="reports"><p class="demo-text">Reports are being generated.</p></ui-tabs-content>
  </ui-tabs>
</div>
```

If `value` is missing, unknown or names a disabled trigger, the first enabled trigger is selected.

### Vertical

`orientation="vertical"` stacks the triggers in a column beside the panels. Up and Down arrows move between them.

```html live
<div class="demo-narrow">
  <ui-tabs orientation="vertical" value="general">
    <ui-tabs-list>
      <ui-tabs-trigger value="general">General</ui-tabs-trigger>
      <ui-tabs-trigger value="members">Members</ui-tabs-trigger>
      <ui-tabs-trigger value="billing">Billing</ui-tabs-trigger>
    </ui-tabs-list>
    <ui-tabs-content value="general"><p class="demo-text">General settings for the workspace.</p></ui-tabs-content>
    <ui-tabs-content value="members"><p class="demo-text">Invite people and manage roles.</p></ui-tabs-content>
    <ui-tabs-content value="billing"><p class="demo-text">Plan, invoices and payment method.</p></ui-tabs-content>
  </ui-tabs>
</div>
```

### Icons in triggers

Icons inside a trigger are sized to `calc(var(--spacing) * 4)`.

```html live
<ui-tabs value="preview">
  <ui-tabs-list>
    <ui-tabs-trigger value="preview">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M2 12s3-7 10-7 10 7 10 7-3 7-10 7S2 12 2 12z" /><circle cx="12" cy="12" r="3" /></svg>
      Preview
    </ui-tabs-trigger>
    <ui-tabs-trigger value="code">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m16 18 6-6-6-6M8 6l-6 6 6 6" /></svg>
      Code
    </ui-tabs-trigger>
  </ui-tabs-list>
</ui-tabs>
```

### Tabs as a filter

A `ui-tabs` without `ui-tabs-content` works as a segmented control. Listen for `change` and read `value`. The
dashboard example uses this to switch the data of a chart.

```html live
<custom-element name="tabs-filter-demo">
  <script type="realm">
    const filter = useState({ range: "7d" });

    function changed(tabs) {
      filter.range = tabs.value;
    }
  </script>
  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      justify-items: center;
    }
    p {
      margin: 0;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>
  <ui-tabs value="7d" onchange="changed(this)">
    <ui-tabs-list>
      <ui-tabs-trigger value="24h">24 hours</ui-tabs-trigger>
      <ui-tabs-trigger value="7d">7 days</ui-tabs-trigger>
      <ui-tabs-trigger value="30d">30 days</ui-tabs-trigger>
    </ui-tabs-list>
  </ui-tabs>
  <p>Showing data for: <slot name="#filter.range"></slot></p>
</custom-element>
<tabs-filter-demo></tabs-filter-demo>
```

## API

### Parts

| Element | Fills | Renders |
| --- | --- | --- |
| `ui-tabs` | | A flex container for the list and the panels. Fills its container's width. |
| `ui-tabs-list` | the default slot of `ui-tabs` | A `role="tablist"` pill around the triggers, with `aria-orientation` and arrow-key navigation. |
| `ui-tabs-trigger` | the default slot of `ui-tabs-list` | A `<button role="tab">` with `aria-selected` and a roving `tabindex`. |
| `ui-tabs-content` | the default slot of `ui-tabs` | The panel, with `role="tabpanel"`. Hidden unless its `value` is selected. |

### Attributes

#### ui-tabs

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | | The `value` of the selected trigger. If it is missing, unknown or names a disabled trigger, the first enabled trigger is selected. Updated when the user selects a tab. |
| `orientation` | `"horizontal"` \| `"vertical"` | `"horizontal"` | Lays the list out as a row above the panels or a column beside them, and sets which arrow keys move between tabs. |

#### ui-tabs-trigger

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | | Identifies the tab. Selecting it shows the `ui-tabs-content` with the same `value`. |
| `disabled` | boolean | `false` | Disables the tab. |

#### ui-tabs-content

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | | The `value` of the trigger that shows this panel. |

`ui-tabs-list` has no attributes.

### Events

| Event | Element | Description |
| --- | --- | --- |
| `change` | `ui-tabs` | Fires when the user selects a different tab, by click or keyboard. Read the new `value` from the element. Bubbles. |

### Child elements

`ui-tabs` watches its `ui-tabs-list` and `ui-tabs-content` children and the `value` and `disabled` attributes of
the triggers and panels, so tabs can be added, removed or renamed at any time.

### CSS parts

| Part | Element | Description |
| --- | --- | --- |
| `list` | `ui-tabs-list` | The `role="tablist"` container. |
| `trigger` | `ui-tabs-trigger` | The tab button. The selected one has `aria-selected="true"`. |

### Accessibility

- The list has `role="tablist"` and `aria-orientation`. Each trigger renders a `<button role="tab">` with
  `aria-selected`.
- Each `ui-tabs-content` has `role="tabpanel"` and is labelled by its trigger.
- Only the selected tab is in the Tab order. Tab moves from it into the visible panel.
- Left and Right arrows (Up and Down when vertical) move to the previous or next tab and select it, wrapping at the
  ends. Home and End select the first and last tab. Disabled tabs are skipped.
- In a right-to-left context, such as inside [Direction](/components/direction/) with `dir="rtl"`, Left and Right
  are swapped.


---

# Aspect Ratio

Source: http://realm.js.org/components/aspect-ratio/

`ui-aspect-ratio` is a block that sizes its height from its width with the CSS `aspect-ratio` property and clips
anything that overflows. It fills the width of its container, so size it with a wrapper. A slotted `<img>`,
`<video>` or `<iframe>` is stretched to fill the box with `object-fit: cover`. Put the radius and background on
the content, not on the box.

```html live
<div class="demo-medium">
  <ui-aspect-ratio ratio="16 / 9">
    <div class="demo-tile">16 / 9</div>
  </ui-aspect-ratio>
</div>
```

## Examples

### Ratios

`ratio` takes any value the CSS `aspect-ratio` property accepts, such as `1 / 1`, `4 / 3` or `2.35`.

```html live
<div class="demo-narrow demo-stack">
  <ui-aspect-ratio ratio="21 / 9">
    <div class="demo-tile">21 / 9</div>
  </ui-aspect-ratio>
  <ui-aspect-ratio ratio="4 / 3">
    <div class="demo-tile">4 / 3</div>
  </ui-aspect-ratio>
  <ui-aspect-ratio ratio="1 / 1">
    <div class="demo-tile">1 / 1</div>
  </ui-aspect-ratio>
</div>
```

### Image

A slotted image covers the whole box and is cropped to the ratio.

```html live
<div class="demo-narrow">
  <ui-aspect-ratio ratio="4 / 3">
    <img class="demo-image" alt="A mountain range at sunset" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 400 200'%3E%3Crect width='400' height='200' fill='%23f4a261'/%3E%3Cpath d='M0 200 120 70l70 80 60-50 150 100z' fill='%23264653'/%3E%3Ccircle cx='300' cy='60' r='28' fill='%23e9c46a'/%3E%3C/svg%3E">
  </ui-aspect-ratio>
</div>
```

### Video embed

```html
<ui-aspect-ratio ratio="16 / 9">
  <iframe src="https://www.youtube-nocookie.com/embed/VIDEO_ID" title="Product tour" allowfullscreen></iframe>
</ui-aspect-ratio>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-aspect-ratio` | (default) | A full-width block at the given ratio that clips overflow. Its default slot takes any content. `<img>`, `<video>` and `<iframe>` fill the box and use `object-fit: cover`. |

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | string | `"16 / 9"` | Width-to-height ratio, as a CSS `aspect-ratio` value. |

### CSS parts

None. The box renders only a slot.

### CSS states and custom properties

The ratio is applied through the reactive custom property `--attr-ratio`, which mirrors the `ratio` attribute.

### Accessibility

The element adds no semantics. Give images an `alt` text and iframes a `title`.


---

# Carousel

Source: http://realm.js.org/components/carousel/

`ui-carousel` is a slideshow built on a native scroll container with CSS scroll snapping, so touch swiping,
trackpads and the scroll wheel work without script. Put the slides, one `ui-carousel-item` each, in a
`ui-carousel-content`. The optional `ui-carousel-previous` and `ui-carousel-next` buttons sit either side of the
track, scroll one slide at a time and are disabled at the ends. The carousel is as wide as its container, so size it
with a wrapper.

```html live
<div class="demo-narrow">
  <ui-carousel>
    <ui-carousel-content>
      <ui-carousel-item>
        <ui-card>
          <ui-card-content>
            <ui-aspect-ratio ratio="1"><div class="demo-tile">1</div></ui-aspect-ratio>
          </ui-card-content>
        </ui-card>
      </ui-carousel-item>
      <ui-carousel-item>
        <ui-card>
          <ui-card-content>
            <ui-aspect-ratio ratio="1"><div class="demo-tile">2</div></ui-aspect-ratio>
          </ui-card-content>
        </ui-card>
      </ui-carousel-item>
      <ui-carousel-item>
        <ui-card>
          <ui-card-content>
            <ui-aspect-ratio ratio="1"><div class="demo-tile">3</div></ui-aspect-ratio>
          </ui-card-content>
        </ui-card>
      </ui-carousel-item>
      <ui-carousel-item>
        <ui-card>
          <ui-card-content>
            <ui-aspect-ratio ratio="1"><div class="demo-tile">4</div></ui-aspect-ratio>
          </ui-card-content>
        </ui-card>
      </ui-carousel-item>
      <ui-carousel-item>
        <ui-card>
          <ui-card-content>
            <ui-aspect-ratio ratio="1"><div class="demo-tile">5</div></ui-aspect-ratio>
          </ui-card-content>
        </ui-card>
      </ui-carousel-item>
    </ui-carousel-content>
    <ui-carousel-previous></ui-carousel-previous>
    <ui-carousel-next></ui-carousel-next>
  </ui-carousel>
</div>
```

## Examples

### Vertical

`orientation="vertical"` snaps slides top to bottom and moves the buttons above and below the track, rotated. A
vertical carousel needs a height. Set `height` in spacing units and the track fills what the buttons leave. Each
slide fills the track.

```html live
<div class="demo-narrow">
  <ui-carousel orientation="vertical" height="56">
    <ui-carousel-content>
      <ui-carousel-item><div class="demo-tile">1</div></ui-carousel-item>
      <ui-carousel-item><div class="demo-tile">2</div></ui-carousel-item>
      <ui-carousel-item><div class="demo-tile">3</div></ui-carousel-item>
    </ui-carousel-content>
    <ui-carousel-previous></ui-carousel-previous>
    <ui-carousel-next></ui-carousel-next>
  </ui-carousel>
</div>
```

### Without buttons

Leave out the previous and next parts for a carousel moved only by swiping, scrolling or the arrow keys.

```html live
<div class="demo-narrow">
  <ui-carousel label="Tips">
    <ui-carousel-content>
      <ui-carousel-item><div class="demo-tile">Swipe</div></ui-carousel-item>
      <ui-carousel-item><div class="demo-tile">Scroll</div></ui-carousel-item>
      <ui-carousel-item><div class="demo-tile">Arrow keys</div></ui-carousel-item>
    </ui-carousel-content>
  </ui-carousel>
</div>
```

### Slide counter

The carousel fires `change` with the index of the visible slide whenever scrolling settles, from the buttons, the
keyboard or a swipe.

```html live
<custom-element name="carousel-counter-demo">
  <script type="realm">
    const slides = useState({
      index: 0,
      get text() {
        return `Slide ${this.index + 1} of 3`;
      },
    });

    function changed(event) {
      slides.index = event.detail.index;
    }
  </script>
  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 2);
      width: min(100%, calc(var(--spacing) * 88));
    }
    .slide {
      display: grid;
      place-items: center;
      height: calc(var(--spacing) * 32);
      border-radius: var(--radius-lg);
      background: var(--muted);
      font-size: var(--text-sm);
    }
    p {
      margin: 0;
      text-align: center;
      font-size: var(--text-sm);
      color: var(--muted-foreground);
    }
  </style>
  <ui-carousel label="Product photos" onchange="changed(event)">
    <ui-carousel-content>
      <ui-carousel-item><div class="slide">Front</div></ui-carousel-item>
      <ui-carousel-item><div class="slide">Side</div></ui-carousel-item>
      <ui-carousel-item><div class="slide">Back</div></ui-carousel-item>
    </ui-carousel-content>
    <ui-carousel-previous></ui-carousel-previous>
    <ui-carousel-next></ui-carousel-next>
  </ui-carousel>
  <p><slot name="#slides.text"></slot></p>
</custom-element>
<carousel-counter-demo></carousel-counter-demo>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-carousel-content` | (default) | The scroll-snapping track (`part="track"`). It is focusable and the arrow keys move between slides. |
| `ui-carousel-item` | (default) of `ui-carousel-content` | One slide, the full width (or height) of the track, borders and padding included. |
| `ui-carousel-previous` | (default) | An outline icon button that scrolls to the previous slide. Left of the track, or above it when vertical. |
| `ui-carousel-next` | (default) | An outline icon button that scrolls to the next slide. Right of the track, or below it when vertical. |

The parts place themselves in the carousel's grid, so their source order does not matter. The default slot of
`ui-carousel-item` takes any content.

### Attributes

#### ui-carousel

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal"` \| `"vertical"` | `"horizontal"` | Scroll and snap direction. A vertical carousel needs a `height`. |
| `label` | string | `"Carousel"` | Accessible name of the region. |
| `height` | number | none | Height in spacing units, so `height="56"` is `calc(var(--spacing) * 56)`. Needed for a vertical carousel. |

`ui-carousel-content`, `ui-carousel-item`, `ui-carousel-previous` and `ui-carousel-next` have no attributes.

### Events

| Event | Detail | Description |
| --- | --- | --- |
| `change` | `{ index: number }` | Fires on `ui-carousel` when scrolling of the track ends. `index` is the zero-based index of the slide in view. Bubbles. |

### CSS parts

| Part | Element | Description |
| --- | --- | --- |
| `track` | `ui-carousel-content` | The scroll container holding the slides. |

### Accessibility

- `ui-carousel` has `role="region"`, `aria-roledescription="carousel"` and the accessible name from `label`.
- Each `ui-carousel-item` has `role="group"` and `aria-roledescription="slide"`.
- The track is focusable. Left and Up arrows scroll to the previous slide, Right and Down arrows to the next.
- The buttons are labelled "Previous slide" and "Next slide" and are disabled on the first and last slide.
- Slides are not hidden from assistive technology, and there is no autoplay.


---

# Direction

Source: http://realm.js.org/components/direction/

`ui-direction` sets the native `dir` attribute on itself and uses `display: contents`, so it adds no box of its own.
Everything inside inherits the direction: text alignment, logical CSS properties such as `margin-inline-start`, and
the keyboard behaviour of components that use `focusgroup`, where Left and Right swap in right-to-left content.

```html live
<ui-direction dir="rtl">
  <div class="demo-narrow demo-stack-tight">
    <ui-breadcrumb label="مسار التنقل">
      <ui-breadcrumb-list>
        <ui-breadcrumb-item><ui-breadcrumb-link href="#">الرئيسية</ui-breadcrumb-link></ui-breadcrumb-item>
        <ui-breadcrumb-separator></ui-breadcrumb-separator>
        <ui-breadcrumb-item><ui-breadcrumb-link href="#">المكونات</ui-breadcrumb-link></ui-breadcrumb-item>
        <ui-breadcrumb-separator></ui-breadcrumb-separator>
        <ui-breadcrumb-item><ui-breadcrumb-page>الاتجاه</ui-breadcrumb-page></ui-breadcrumb-item>
      </ui-breadcrumb-list>
    </ui-breadcrumb>
    <ui-input aria-label="بحث" placeholder="ابحث في الوثائق"></ui-input>
    <div class="demo-row-tight">
      <ui-button>حفظ</ui-button>
      <ui-button variant="outline">إلغاء</ui-button>
    </div>
  </div>
</ui-direction>
```

## Examples

### Keyboard in right-to-left content

Tabs, toggle groups and other components built on `focusgroup` read the direction. In this right-to-left tab list
the first tab is on the right, and the Left arrow moves to the next tab.

```html live
<ui-direction dir="rtl">
  <div class="demo-narrow">
    <ui-tabs value="account">
      <ui-tabs-list>
        <ui-tabs-trigger value="account">الحساب</ui-tabs-trigger>
        <ui-tabs-trigger value="password">كلمة المرور</ui-tabs-trigger>
        <ui-tabs-trigger value="team">الفريق</ui-tabs-trigger>
      </ui-tabs-list>
      <ui-tabs-content value="account"><p class="demo-text">إعدادات الحساب.</p></ui-tabs-content>
      <ui-tabs-content value="password"><p class="demo-text">تغيير كلمة المرور.</p></ui-tabs-content>
      <ui-tabs-content value="team"><p class="demo-text">إدارة الفريق.</p></ui-tabs-content>
    </ui-tabs>
  </div>
</ui-direction>
```

### Left to right inside right to left

Directions nest. `dir="ltr"` restores left-to-right for a part of the page, such as a code sample.

```html live
<ui-direction dir="rtl">
  <div class="demo-narrow demo-stack-tight">
    <p class="demo-text">حمّل المكوّنات بالوسم التالي:</p>
    <ui-direction dir="ltr">
      <p class="demo-text"><code>&lt;import-element from="ui.html"&gt;</code></p>
    </ui-direction>
  </div>
</ui-direction>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `dir` | `"ltr"` \| `"rtl"` | `"ltr"` | Text direction for the content. Written back to the native `dir` attribute, so it is always present on the element. |

### Slots

| Slot | Description |
| --- | --- |
| (default) | The content that takes the direction. |

### Accessibility

The native `dir` attribute is what browsers and assistive technology use, so screen readers and text selection
follow the direction. Set `lang` alongside it (for example `lang="ar"`) when the content is in another language.


---

# Resizable

Source: http://realm.js.org/components/resizable/

`ui-resizable` is a flex container for `ui-resizable-panel` elements separated by `ui-resizable-handle` elements.
Each panel's `size` is its share of the group. Dragging a handle, or focusing it and pressing the arrow keys,
moves size from one neighbouring panel to the other, never below either panel's `min`. The group is as wide as its
container. Give it a `height` in spacing units (or size its parent), and add `variant="outline"` for a border.

```html live
<div class="demo-medium">
<ui-resizable variant="outline" height="48">
  <ui-resizable-panel size="50">
    <div class="demo-tile">One</div>
  </ui-resizable-panel>
  <ui-resizable-handle></ui-resizable-handle>
  <ui-resizable-panel size="50">
    <div class="demo-tile">Two</div>
  </ui-resizable-panel>
</ui-resizable>
</div>
```

## Examples

### Vertical

`direction="vertical"` stacks the panels. Drag the handle up and down, or use the Up and Down arrows.

```html live
<div class="demo-narrow">
<ui-resizable direction="vertical" variant="outline" height="64">
  <ui-resizable-panel size="30">
    <div class="demo-tile">Header</div>
  </ui-resizable-panel>
  <ui-resizable-handle></ui-resizable-handle>
  <ui-resizable-panel size="70">
    <div class="demo-tile">Content</div>
  </ui-resizable-panel>
</ui-resizable>
</div>
```

### Visible grip

Add `handle` to a handle to draw a grip on it, which makes the drag target easier to see.

```html live
<div class="demo-medium">
<ui-resizable variant="outline" height="40">
  <ui-resizable-panel size="25" min="15">
    <div class="demo-tile">Sidebar</div>
  </ui-resizable-panel>
  <ui-resizable-handle handle></ui-resizable-handle>
  <ui-resizable-panel size="75" min="40">
    <div class="demo-tile">Content</div>
  </ui-resizable-panel>
</ui-resizable>
</div>
```

### Nested groups

A panel can hold another group in the other direction.

```html live
<div class="demo-medium">
<ui-resizable variant="outline" height="56">
  <ui-resizable-panel size="40">
    <div class="demo-tile">One</div>
  </ui-resizable-panel>
  <ui-resizable-handle handle></ui-resizable-handle>
  <ui-resizable-panel size="60">
    <ui-resizable direction="vertical">
      <ui-resizable-panel size="25">
        <div class="demo-tile">Two</div>
      </ui-resizable-panel>
      <ui-resizable-handle handle></ui-resizable-handle>
      <ui-resizable-panel size="75">
        <div class="demo-tile">Three</div>
      </ui-resizable-panel>
    </ui-resizable>
  </ui-resizable-panel>
</ui-resizable>
</div>
```

## API

### Attributes

#### ui-resizable

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | `"horizontal"` \| `"vertical"` | `"horizontal"` | Lays the panels out in a row or a column. Handles read it when they connect. |
| `height` | number | none | Height in spacing units, so `height="48"` is `calc(var(--spacing) * 48)`. Without it the group fills its parent's height. |
| `variant` | `"default"` \| `"outline"` | `"default"` | `outline` adds a 1px border and `var(--radius-lg)` corners. |

#### ui-resizable-panel

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | number | `50` | The panel's share of the group, used as its `flex-grow`. Between 0 and 100. Make the sizes in a group add up to 100 so they read as percentages. Updated while resizing. |
| `min` | number | `10` | The smallest `size` a handle can shrink the panel to. At least 0. |

#### ui-resizable-handle

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | boolean | `false` | Shows a visible grip in the middle of the handle. |

### Properties and methods

`ui-resizable-panel` exposes `size` and `min` as properties. Set `size` from script to resize a panel. The handles
read both properties from the panels on either side.

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-resizable-panel` | (default) | One panel. Its content scrolls when it overflows. |
| `ui-resizable-handle` | (default) | A separator between two panels that resizes them. |

Panels and handles alternate in the default slot of `ui-resizable`. The default slot of a panel takes any content,
including another `ui-resizable`.

### CSS parts

| Part | Element | Description |
| --- | --- | --- |
| `grip` | `ui-resizable-handle` | The grip shown with the `handle` attribute. |

### CSS states and custom properties

- `ui-resizable-handle:state(vertical)` matches handles in a vertical group, which are horizontal lines.
- `ui-resizable-panel` applies its size through the reactive custom property `--attr-size`.

### Accessibility

- Each handle has `role="separator"`, `aria-orientation` (`vertical` between side-by-side panels, `horizontal`
  between stacked panels), `aria-valuemin="0"` and `aria-valuemax="100"`. After a resize, `aria-valuenow` holds the
  size of the panel before the handle.
- Handles are in the Tab order. Left and Up arrows shrink the panel before the handle by 5, Right and Down arrows
  grow it by 5, within both panels' `min`.
- Dragging uses pointer capture, so the drag continues when the pointer leaves the handle.
- Give a handle an `aria-label` that says what it resizes, for example `aria-label="Resize sidebar"`.


---

# Scroll Area

Source: http://realm.js.org/components/scroll-area/

`ui-scroll-area` wraps its content in a native scrolling viewport with a thin scrollbar in the theme's border colour.
Scrolling, momentum and keyboard scrolling are the browser's own. Give it a `height` (or a `width` for horizontal
scrolling) in spacing units. The content scrolls inside it. `variant="outline"` adds a border.

```html live
<ui-scroll-area variant="outline" width="48" height="72">
  <ui-item-group aria-label="Tags">
    <ui-item size="sm">v1.2.0-beta.50</ui-item>
    <ui-separator></ui-separator>
    <ui-item size="sm">v1.2.0-beta.49</ui-item>
    <ui-separator></ui-separator>
    <ui-item size="sm">v1.2.0-beta.48</ui-item>
    <ui-separator></ui-separator>
    <ui-item size="sm">v1.2.0-beta.47</ui-item>
    <ui-separator></ui-separator>
    <ui-item size="sm">v1.2.0-beta.46</ui-item>
    <ui-separator></ui-separator>
    <ui-item size="sm">v1.2.0-beta.45</ui-item>
    <ui-separator></ui-separator>
    <ui-item size="sm">v1.2.0-beta.44</ui-item>
    <ui-separator></ui-separator>
    <ui-item size="sm">v1.2.0-beta.43</ui-item>
    <ui-separator></ui-separator>
    <ui-item size="sm">v1.2.0-beta.42</ui-item>
    <ui-separator></ui-separator>
    <ui-item size="sm">v1.2.0-beta.41</ui-item>
    <ui-separator></ui-separator>
    <ui-item size="sm">v1.2.0-beta.40</ui-item>
    <ui-separator></ui-separator>
    <ui-item size="sm">v1.2.0-beta.39</ui-item>
  </ui-item-group>
</ui-scroll-area>
```

## Examples

### Horizontal

`orientation="horizontal"` scrolls sideways and clips vertical overflow. The image below keeps its own `width`
and `height` attributes, so it is wider than the box, which fills a wrapper.

```html live
<div class="demo-medium">
  <ui-scroll-area orientation="horizontal" variant="outline">
    <img width="960" height="240" alt="A mountain range at sunset" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 960 240'%3E%3Crect width='960' height='240' fill='%23f4a261'/%3E%3Ccircle cx='720' cy='70' r='30' fill='%23e9c46a'/%3E%3Cpath d='M0 240 140 90l90 90 110-120 150 180 120-100 140 110 110-80 100 60v10z' fill='%23264653'/%3E%3C/svg%3E">
  </ui-scroll-area>
</div>
```

### Both directions

`orientation="both"` scrolls in both directions, for example to pan a large image or a wide table in a
fixed-size box.

```html live
<div class="demo-medium">
  <ui-scroll-area orientation="both" variant="outline" height="60">
    <img width="800" height="600" alt="A route drawn on a grid map" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 800 600'%3E%3Cdefs%3E%3Cpattern id='g' width='40' height='40' patternUnits='userSpaceOnUse'%3E%3Cpath d='M40 0H0v40' fill='none' stroke='%23264653' stroke-opacity='.25'/%3E%3C/pattern%3E%3C/defs%3E%3Crect width='800' height='600' fill='%23e9f5f2'/%3E%3Crect width='800' height='600' fill='url(%23g)'/%3E%3Cpath d='M60 520C200 380 300 460 420 300S640 120 740 80' fill='none' stroke='%23f4a261' stroke-width='8' stroke-linecap='round'/%3E%3Ccircle cx='60' cy='520' r='14' fill='%23264653'/%3E%3Ccircle cx='740' cy='80' r='14' fill='%23e76f51'/%3E%3C/svg%3E">
  </ui-scroll-area>
</div>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-scroll-area` | (default) | A clipped box with a focusable scrolling viewport. Its default slot takes any content, which scrolls inside the viewport. |

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"vertical"` \| `"horizontal"` \| `"both"` | `"vertical"` | Which directions scroll. Overflow in the other direction is clipped. |
| `width` | number | none | Width in spacing units (`calc(var(--spacing) * width)`). Without it the element fills its container. |
| `height` | number | none | Height in spacing units. Without it the element grows with its content and nothing scrolls vertically. |
| `variant` | `"default"` \| `"outline"` | `"default"` | `outline` adds a 1px border in `var(--border)` with `var(--radius-md)` corners. |

### CSS parts

| Part | Description |
| --- | --- |
| `viewport` | The scrolling container. Style `scrollbar-color` or `scrollbar-width` here to change the scrollbar. |

### Accessibility

- The viewport is focusable (`tabindex="0"`) and shows a focus ring, so keyboard users can scroll it with the arrow
  keys, Page Up, Page Down, Home and End.
- The viewport inherits the element's border radius, so the focus ring follows rounded corners, including the
  `outline` variant.


---

# Attachment

Source: http://realm.js.org/components/attachment/

`ui-attachment` shows a file attached to a message or a form, with a small preview area, the file name, its size and
room for actions such as remove. The name is a link with the `download` attribute, so clicking it downloads the file from
`href` under that name. Long names are truncated with an ellipsis.

The preview goes in a `ui-attachment-media` child and the buttons in a `ui-attachment-actions` child. Both place
themselves before and after the name, whatever their position in the source.

```html live
<ui-attachment name="quarterly-report.pdf" size="1.2 MB" href="data:text/plain,Quarterly%20report">
  <ui-attachment-media>
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M14 3H6v18h12V7Z" /><path d="M14 3v4h4" /></svg>
  </ui-attachment-media>
</ui-attachment>
```

## Examples

### With actions

Put buttons in `ui-attachment-actions`. Give icon buttons an `aria-label` that says what they do to which file.

```html live
<custom-element name="attachment-list-demo">
  <script type="realm">
    const files = useState({
      list: [
        { id: 1, name: "design-review.fig", size: "4.8 MB", remove: "Remove design-review.fig" },
        { id: 2, name: "meeting-notes.md", size: "6 KB", remove: "Remove meeting-notes.md" },
      ],
    });

    function remove(file) {
      files.list.splice(files.list.indexOf(file), 1);
    }
  </script>

  <style type="realm">
    ul {
      display: flex;
      flex-wrap: wrap;
      gap: calc(var(--spacing) * 2);
      margin: 0;
      padding: 0;
      list-style: none;
    }
    ui-button svg {
      width: calc(var(--spacing) * 4);
      height: calc(var(--spacing) * 4);
    }
  </style>

  <ul>
    <li repeat="#files.list" as="file" key="id">
      <ui-attachment _name="#file.name" _size="#file.size">
        <ui-attachment-media>
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M14 3H6v18h12V7Z" /><path d="M14 3v4h4" /></svg>
        </ui-attachment-media>
        <ui-attachment-actions>
          <ui-button variant="ghost" size="icon-xs" _aria-label="#file.remove" onclick="remove(file)">
            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12" /></svg>
          </ui-button>
        </ui-attachment-actions>
      </ui-attachment>
    </li>
  </ul>
</custom-element>
<div class="demo-medium"><attachment-list-demo></attachment-list-demo></div>
```

### Image preview

`ui-attachment-media` is a rounded square with hidden overflow, and an `<img>` inside it covers the square, so it
works as a thumbnail.

```html live
<ui-attachment name="sunset.svg" size="1 KB" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' fill='%23f59e0b'/%3E%3Ccircle cx='16' cy='20' r='8' fill='%23f97316'/%3E%3C/svg%3E">
  <ui-attachment-media>
    <img alt="" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' fill='%23f59e0b'/%3E%3Ccircle cx='16' cy='20' r='8' fill='%23f97316'/%3E%3C/svg%3E">
  </ui-attachment-media>
</ui-attachment>
```

### In a message

```html live
<div class="demo-medium">
  <ui-message align="end">
    <ui-message-avatar>
      <ui-avatar><ui-avatar-fallback>ME</ui-avatar-fallback></ui-avatar>
    </ui-message-avatar>
    <ui-bubble align="end">Here is the contract.</ui-bubble>
    <ui-attachment name="contract-final.pdf" size="320 KB" href="data:text/plain,Contract">
      <ui-attachment-media>
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M14 3H6v18h12V7Z" /><path d="M14 3v4h4" /></svg>
      </ui-attachment-media>
    </ui-attachment>
  </ui-message>
</div>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-attachment` | (root) | The chip with the file name link and size. |
| `ui-attachment-media` | `media` | A muted rounded square before the name for a file icon (`<svg>`, 16px) or a thumbnail `<img>`. |
| `ui-attachment-actions` | `actions` | A row of buttons after the name, such as remove or open. |

The parts set their own `slot`, so they go directly inside `ui-attachment` with no attributes. The default slot of
each part takes any content.

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | string | | File name. Shown as the link text and used as the `download` file name. |
| `size` | string | | Human-readable size, such as `1.2 MB`. Hidden when empty. |
| `href` | string | | URL of the file. Without it the name is not a link. |

### CSS parts

| Part | Description |
| --- | --- |
| `content` | The column with the name and size. |
| `title` | The file name link. |

### Accessibility

The file name is a native link with `download`, so it is focusable and announced as a link when `href` is set. The
attachment shows a focus ring when anything inside it has focus. Mark icons in `ui-attachment-media` with
`aria-hidden="true"` and give thumbnails an empty `alt` when the file name already says what they are.


---

# Bubble

Source: http://realm.js.org/components/bubble/

`ui-bubble` is the rounded box around the text of a chat message. It sizes to its content up to 80% of the
container's width, wraps long words, and can align to the end of a flex column for messages sent by the current user.
A `ui-bubble-reactions` child adds a row below the bubble for reaction chips or small actions.

Use it inside [`ui-message`](/components/message/) together with an avatar and a timestamp, or on its own in a flex column.

```html live
<div class="demo-medium demo-stack-tight">
  <ui-message>
    <ui-bubble variant="muted">Did the deploy go out?</ui-bubble>
  </ui-message>
  <ui-message align="end">
    <ui-bubble align="end">Yes, about ten minutes ago. Everything is green.</ui-bubble>
  </ui-message>
</div>
```

## Examples

### Variants

`variant` is `default` (primary colour), `secondary`, `muted`, `outline` or `ghost`. Ghost removes the box and lets
the text use the full width, which suits long assistant replies.

```html live
<div class="demo-medium demo-stack-tight">
  <ui-bubble>Default</ui-bubble>
  <ui-bubble variant="secondary">Secondary</ui-bubble>
  <ui-bubble variant="muted">Muted</ui-bubble>
  <ui-bubble variant="outline">Outline</ui-bubble>
  <ui-bubble variant="ghost">Ghost bubbles have no background or padding, so longer text reads like a normal paragraph.</ui-bubble>
</div>
```

### Alignment

`align="end"` sets `align-self: flex-end`, which pushes the bubble to the end of a flex column such as the content
column of `ui-message`. Set `align` on the message as well so the avatar moves to the other side.

```html live
<div class="demo-medium">
  <ui-message>
    <ui-bubble variant="secondary">Start</ui-bubble>
    <ui-bubble align="end">End</ui-bubble>
  </ui-message>
</div>
```

### Reactions

Put reactions or small actions in `ui-bubble-reactions`. It places itself below the bubble.

```html live
<div class="demo-medium">
  <ui-bubble variant="muted">
    Lunch at noon?
    <ui-bubble-reactions>
      <ui-badge variant="outline" shape="pill">+1 2</ui-badge>
      <ui-badge variant="outline" shape="pill">Yes 1</ui-badge>
    </ui-bubble-reactions>
  </ui-bubble>
</div>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-bubble` | (root) | The rounded box around the message content. |
| `ui-bubble-reactions` | `reactions` | A wrapping row below the bubble for reactions or actions. |

`ui-bubble-reactions` sets its own `slot`, so it goes directly inside `ui-bubble` with no attributes. Everything
else in `ui-bubble` is the message content. The default slot of each part takes any content.

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default"` \| `"secondary"` \| `"muted"` \| `"outline"` \| `"ghost"` | `"default"` | Background and text colour. |
| `align` | `"start"` \| `"end"` | `"start"` | `end` sets `align-self: flex-end` on the bubble. |

### CSS parts

| Part | Description |
| --- | --- |
| `content` | The rounded box around the message content. |

### Accessibility

`ui-bubble` adds no roles, and the reading order is the source order. Put the conversation in a
[`ui-message-scroller`](/components/message-scroller/) so new messages are announced.


---

# Code Block

Source: http://realm.js.org/components/code-block/

`ui-code-block` shows code in a bordered, horizontally scrolling block with the language name and a copy button in
the top corner. The copy button writes the block's text content to the clipboard with
`navigator.clipboard.writeText()` and shows a check mark for 1.5 seconds. It does not highlight syntax. Slot
highlighted markup if you need colours.

Whitespace is preserved, so put the code in a `<pre>` (or start it right after the opening tag) and escape `<` as
`&lt;`. A slotted `<pre>` gets no margin. The block is as wide as its container, so size it with a wrapper.

```html live
<div class="demo-medium">
  <ui-code-block language="html"><pre>&lt;script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js"&gt;&lt;/script&gt;</pre></ui-code-block>
</div>
```

## Examples

### Multi-line code

```html live
<div class="demo-medium">
<ui-code-block language="html"><pre>&lt;custom-element name="hello-world"&gt;
  &lt;script&gt;
    defineProps({ name: prop.string().default("world") });
  &lt;/script&gt;
  &lt;p&gt;Hello, &lt;slot name="@name"&gt;&lt;/slot&gt;!&lt;/p&gt;
&lt;/custom-element&gt;</pre></ui-code-block>
</div>
```

### In a message

Code blocks fit inside a `ui-message` next to ghost bubbles for assistant replies.

```html live
<div class="demo-medium">
  <ui-message>
    <ui-message-header>Assistant</ui-message-header>
    <ui-bubble variant="ghost">Read the JSON body of a response like this:</ui-bubble>
    <ui-code-block language="js"><pre>const response = await fetch("/api/user");
const user = await response.json();</pre></ui-code-block>
  </ui-message>
</div>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `language` | string | | Label shown in the top corner, in upper case. Display only. |

### Parts

`ui-code-block` has no child parts. Its default slot takes the code, usually a `<pre>`. Its trimmed `textContent` is
what the copy button copies.

### CSS parts

| Part | Description |
| --- | --- |
| `code` | The scrolling area around the code (`white-space: pre`). |
| `bar` | The corner bar with the language label and the copy button. |

### Accessibility

The copy button is a `ui-button` with `aria-label="Copy code"`. The check mark that confirms the copy is visual only, and
nothing is announced.


---

# Marker

Source: http://realm.js.org/components/marker/

`ui-marker` is a full-width row of small, muted text with an optional leading icon. Use it in a conversation for
things that are not messages: a date separator, "Ana joined the channel", or a label above a group of items. An
icon is a leading `<svg>` child, sized to `calc(var(--spacing) * 4)`.

```html live
<div class="demo-medium demo-stack">
  <ui-marker variant="separator">Today</ui-marker>
  <ui-marker>
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M16 21v-2a4 4 0 0 0-8 0v2" /><circle cx="12" cy="7" r="4" /></svg>
    Ana joined the channel
  </ui-marker>
</div>
```

## Examples

### Variants

`default` is plain text. `separator` draws a line on both sides of the text. `border` adds a line underneath.

```html live
<div class="demo-medium demo-stack">
  <ui-marker>Default marker</ui-marker>
  <ui-marker variant="separator">Separator marker</ui-marker>
  <ui-marker variant="border">Border marker</ui-marker>
</div>
```

### In a conversation

```html live
<div class="demo-medium demo-stack">
  <ui-marker variant="separator">Yesterday</ui-marker>
  <ui-message>
    <ui-message-avatar><ui-avatar><ui-avatar-fallback>AL</ui-avatar-fallback></ui-avatar></ui-message-avatar>
    <ui-bubble variant="muted">Can someone review my pull request?</ui-bubble>
  </ui-message>
  <ui-marker variant="separator">Today</ui-marker>
  <ui-message align="end">
    <ui-message-avatar><ui-avatar><ui-avatar-fallback>ME</ui-avatar-fallback></ui-avatar></ui-message-avatar>
    <ui-bubble align="end">Approved, merging now.</ui-bubble>
  </ui-message>
</div>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default"` \| `"separator"` \| `"border"` | `"default"` | `separator` draws lines on both sides. `border` draws a line below. |

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-marker` | (root) | A full-width row of small muted text. |

The default slot takes the text and an optional leading `<svg>` icon.

### CSS parts

None. The shadow root is a single slot. Style the host.

### Accessibility

`ui-marker` adds no role. The separator lines are drawn with CSS and are not announced. Mark a decorative icon with
`aria-hidden="true"`.


---

# Message

Source: http://realm.js.org/components/message/

`ui-message` is one row of a conversation. It places an avatar next to a column with an optional header (name), the
message content (usually one or more [`ui-bubble`](/components/bubble/) elements) and an optional footer (time or status).
`align="end"` mirrors the row for messages sent by the current user. The avatar moves to the end and the content
aligns right.

The avatar, header and footer are child parts: `ui-message-avatar`, `ui-message-header` and `ui-message-footer`. They
place themselves, so source order does not matter for them. Everything else is the message content.

```html live
<div class="demo-medium demo-stack">
  <ui-message>
    <ui-message-avatar>
      <ui-avatar><ui-avatar-fallback>OM</ui-avatar-fallback></ui-avatar>
    </ui-message-avatar>
    <ui-message-header>Olivia Martin</ui-message-header>
    <ui-bubble variant="muted">Hi, how can I help you today?</ui-bubble>
    <ui-message-footer>10:02</ui-message-footer>
  </ui-message>
  <ui-message align="end">
    <ui-message-avatar>
      <ui-avatar><ui-avatar-fallback>ME</ui-avatar-fallback></ui-avatar>
    </ui-message-avatar>
    <ui-bubble align="end">I cannot sign in to my account.</ui-bubble>
    <ui-message-footer>10:03 · Read</ui-message-footer>
  </ui-message>
</div>
```

## Examples

### Several bubbles in one message

The content column stacks its children with a gap, so consecutive bubbles from the same sender go in one
`ui-message`.

```html live
<div class="demo-medium">
  <ui-message>
    <ui-message-avatar>
      <ui-avatar><ui-avatar-fallback>JL</ui-avatar-fallback></ui-avatar>
    </ui-message-avatar>
    <ui-message-header>Jackson Lee</ui-message-header>
    <ui-bubble variant="muted">The new build is up.</ui-bubble>
    <ui-bubble variant="muted">Release notes are in the usual place.</ui-bubble>
    <ui-attachment name="release-notes.pdf" size="84 KB" href="data:text/plain,Release%20notes">
      <ui-attachment-media>
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M14 3H6v18h12V7Z" /><path d="M14 3v4h4" /></svg>
      </ui-attachment-media>
    </ui-attachment>
  </ui-message>
</div>
```

### Assistant reply

A ghost bubble without an avatar suits long-form replies.

```html live
<div class="demo-medium">
  <ui-message>
    <ui-message-header>Assistant</ui-message-header>
    <ui-bubble variant="ghost">To reset your password, open Settings, choose Security and click Reset password. A link
      is sent to your email address and stays valid for one hour.</ui-bubble>
  </ui-message>
</div>
```

## API

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-message` | (root) | The row, with the avatar beside a column with header, content and footer. |
| `ui-message-avatar` | `avatar` | Wraps a [`ui-avatar`](/components/avatar/), aligned to the bottom of the row. |
| `ui-message-header` | `header` | A small muted line above the content, such as the sender name and time. |
| `ui-message-footer` | `footer` | A small muted line below the content, such as the time or a read receipt. |

The parts set their own `slot`, so they go directly inside `ui-message` with no attributes. Any other child (bubbles,
attachments, code blocks) is the message content. The default slot of each part takes any content.

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start"` \| `"end"` | `"start"` | `end` reverses the row and aligns the content to the end. |

### CSS parts

| Part | Description |
| --- | --- |
| `content` | The column with the header, content and footer. |

### Accessibility

`ui-message` adds no roles. Screen readers read the header, content and footer in source order, so put the sender
name in `ui-message-header` rather than relying on the avatar.


---

# Message Scroller

Source: http://realm.js.org/components/message-scroller/

`ui-message-scroller` is the scrolling area of a chat. It starts scrolled to the bottom and stays pinned there as
messages are added, but only while the user is already at (or within `threshold` pixels of) the bottom. When the user
scrolls up to read history, new messages no longer move the view and a "Jump to latest" button appears. Clicking it
scrolls smoothly back down.

Give the scroller a height with the `height` attribute (in spacing units, `height="60"` is
`calc(var(--spacing) * 60)`) or let a flex or grid layout size it. It is always 100% wide. The viewport has
`role="log"` and `aria-live="polite"`.

```html live
<custom-element name="message-scroller-demo">
  <script type="realm">
    const chat = useState({
      next: 6,
      messages: [
        { id: 1, align: "start", text: "Are we still on for the launch review?" },
        { id: 2, align: "end", text: "Yes, 3pm in the big room." },
        { id: 3, align: "start", text: "Great. Can you bring the metrics?" },
        { id: 4, align: "end", text: "Already in the deck." },
        { id: 5, align: "start", text: "Perfect, see you there." },
      ],
    });

    const REPLIES = ["On my way.", "Running five minutes late.", "Room changed to 4B.", "Starting now."];

    function send() {
      const text = REPLIES[chat.next % REPLIES.length];
      chat.messages.push({ id: chat.next, align: chat.next % 2 ? "start" : "end", text });
      chat.next++;
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      width: 100%;
      max-width: calc(var(--spacing) * 112);
    }
    ui-message-scroller {
      border: 1px solid var(--border);
      border-radius: var(--radius-lg);
    }
    .messages {
      display: flex;
      flex-direction: column;
      gap: calc(var(--spacing) * 2);
      padding: calc(var(--spacing) * 4);
    }
  </style>

  <ui-message-scroller height="60">
    <div class="messages">
      <repeat-list of="#chat.messages" as="message" key="id">
        <ui-bubble variant="muted" _align="#message.align"><slot name="#message.text"></slot></ui-bubble>
      </repeat-list>
    </div>
  </ui-message-scroller>
  <ui-button variant="outline" onclick="send()">Receive a message</ui-button>
</custom-element>
<message-scroller-demo></message-scroller-demo>
```

Scroll up in the log and click "Receive a message". The view stays where it is and "Jump to latest" appears.

## Examples

### Threshold

`threshold` is how close to the bottom, in pixels, still counts as "at the bottom" (default `48`). Use `0` to only
follow new messages when the view is exactly at the end.

```html live
<div class="demo-medium">
  <ui-message-scroller threshold="0" height="40">
    <div class="demo-stack">
      <ui-marker variant="separator">Monday</ui-marker>
      <ui-message>
        <ui-message-avatar><ui-avatar><ui-avatar-fallback>AL</ui-avatar-fallback></ui-avatar></ui-message-avatar>
        <ui-bubble variant="muted">Morning! Standup moved to 9:30.</ui-bubble>
      </ui-message>
      <ui-message align="end">
        <ui-message-avatar><ui-avatar><ui-avatar-fallback>ME</ui-avatar-fallback></ui-avatar></ui-message-avatar>
        <ui-bubble align="end">Thanks for the heads-up.</ui-bubble>
      </ui-message>
      <ui-marker variant="separator">Today</ui-marker>
      <ui-message>
        <ui-message-avatar><ui-avatar><ui-avatar-fallback>AL</ui-avatar-fallback></ui-avatar></ui-message-avatar>
        <ui-bubble variant="muted">Release is tagged.</ui-bubble>
      </ui-message>
      <ui-message align="end">
        <ui-message-avatar><ui-avatar><ui-avatar-fallback>ME</ui-avatar-fallback></ui-avatar></ui-message-avatar>
        <ui-bubble align="end">Shipping it.</ui-bubble>
      </ui-message>
    </div>
  </ui-message-scroller>
</div>
```

## API

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `threshold` | number | `48` | Distance from the bottom, in pixels, within which the scroller stays pinned to new content. Minimum `0`. |
| `height` | number | | Height in spacing units, so `height="60"` is `calc(var(--spacing) * 60)`. Without it, size the scroller from its layout. |

### Parts

| Part | Slot | Renders |
| --- | --- | --- |
| `ui-message-scroller` | (root) | The scrolling log and the "Jump to latest" button. |

The default slot takes the messages and any other content. Any change inside (added nodes, text changes) scrolls to
the bottom while pinned.

### CSS parts

| Part | Description |
| --- | --- |
| `viewport` | The scrolling element (`role="log"`, `aria-live="polite"`). |

### CSS states and custom properties

| Name | Description |
| --- | --- |
| `:state(attr-height)` | Matches while `height` is set. The height comes from `var(--attr-height)`. |
| `:state(state-scroll-pinned)` | Matches while the view is within `threshold` of the bottom. The "Jump to latest" button is hidden in this state. |

### Accessibility

- The viewport has `role="log"` and `aria-live="polite"`, so screen readers announce new messages.
- The "Jump to latest" button is a regular `ui-button`, reachable with Tab while it is shown.


---

# REALM is dead, long live REALM

Source: http://realm.js.org/blog/realm-v2/

*20 October 2026 · Ribhararnus Pracutian*

In June 2025 I put REALM into [maintenance mode](/blog/project-is-under-maintenance-mode/) and told anyone starting a new project to use something else. REALM is now back as v2, a rewrite. This post covers why v1 stopped, what changed, and how to start.

## Why v1 stopped

The maintenance post gave three reasons:

- Shadow DOM and the Web Component APIs kept changing across browsers. Keeping v1 working everywhere took more time than one person had.
- Good component libraries had appeared, with communities behind them.
- I no longer used REALM in anything I shipped, so I got no feedback from actual use.

There was a fourth reason I did not write down. v1 was built quickly and had no test suite. A later audit found 22 confirmed bugs, including the one that broke Unicons when a page imported many icons.

## Why v2 exists

Two things changed.

First, the platform settled. The APIs v2 depends on, such as `ElementInternals`, custom states (`:state()`), `adoptedStyleSheets` and `AbortSignal`, now behave the same in Chromium, Firefox and WebKit. v2 runs its full test suite in all three browsers on every change, so I find out when that stops being true.

Second, REALM's original goal still holds. You can build a working app with a browser, a text editor, HTML files and one script tag from a CDN. There is no npm, bundler or compiler. Most front-end tools assume a build step before anything shows on screen. REALM does not.

The design also suits code assistants. A REALM component is plain HTML with a short script, and each feature uses the platform's own names: `<slot>`, `onclick`, `fetch`, `action`, `method`. There are no template expressions or custom syntax to learn, so language models can read and write REALM code with few mistakes. The site supports this:

- [llms.txt](/llms.txt) lists every page, and [llms-full.txt](/llms-full.txt) holds the whole documentation in one file.
- Every page has a Markdown copy. Add `.md` to the address, or use the "View as Markdown" link at the bottom of each page.
- The runtime's behaviour is written down as [specifications](https://github.com/realmorg/realm/tree/main/openspec/specs). Every scenario in them is a test with the same name, so the specs and the code stay in sync.

## What changed from v1

### One tag, three parts

In v1, everything was a tag. Data lived in `<element-state>`, changes were `<set-state>`, clicks were `<trigger-event>` inside `<element-flow>`, requests were `<http-request>` with `<response-ok>` and `<response-fail>`, and markup sat inside a `<template>`. Simple components were pleasant to write, but anything unusual needed deep trees of tags.

In v2, a component is one `<custom-element>` with a `<script>`, a `<style>` and markup:

```html
<custom-element name="counter-button">
  <script type="realm">
    const counter = useState({ count: 0 });

    function increment() {
      counter.count++;
    }
  </script>

  <style type="realm">
    button { font-weight: bold; }
  </style>

  <button onclick="increment()">Clicked <slot name="#counter.count"></slot> times</button>
</custom-element>

<counter-button></counter-button>
```

The script is plain JavaScript with a few named helpers: `defineProps` for typed attributes, `useState` for state, `observe` for side effects. REALM builds each component in the browser.

### Native slots and handlers

- Values are shown with native `<slot name="#…">` and `<slot name="@…">` elements.
- Events are native `on*` attributes, such as `onclick="save(item)"`, that call functions from the script.
- Attributes are bound with v1's `_` prefix: `_href="#link.url"`.
- `<is-visible>`, `<is-hidden>` and `<repeat-list>` are still there. Lists take a `key`, so focus and typed text survive reordering, and the `repeat` attribute works inside tables and selects.

### Requests as attributes

`fetch`, `into`, `render`, `busy`, `trigger`, `poll` and a few others go on the element that starts the request. Forms use their native `action` and `method`. Stale requests are cancelled, so an older, slower response can no longer overwrite a newer one. Results fire the browser's own `load` and `error` events. See [Fetching data](/docs/fetching/).

### import-element

`<import-element from="…">` loads an HTML file and defines every component in it. In v2 each URL is fetched once, however many tags ask for it, and defining a component twice does no harm. This fixes the bug that broke Unicons. See [Importing components](/docs/importing/).

### Other changes

- **Fine-grained updates.** A change updates only the slots and bindings that read it.
- **Typed props.** `prop.number().int().min(0).default(0)`. Invalid values warn and fall back instead of crashing.
- **Form fields.** `form-associated` components submit, reset, validate and restore like built-in inputs.
- **Accessibility.** Default roles, `delegates-focus`, and arrow-key navigation through `focusgroup`.
- **Styling from state.** `:host(:state(attr-variant-is-outline))`, `var(--attr-*)` and `var(--state-*)` replace v1's regex-based CSS rewriting.
- **Stores.** `defineStore` shares state between components, with persistence that keeps value types.
- **Cleanup.** Every listener, timer, observer and request a component starts stops when the component is removed.
- **Security.** No `eval`, `new Function` or `blob:` URLs. HTML values are sanitised, and nonce-based Content Security Policies work.

### REALM UI

`@realmorg/ui` is a set of about sixty accessible `ui-*` components, such as buttons, dialogs, menus, tabs and data tables. They are written with REALM, and this website uses them. Browse them in [Components](/components/).

### Unicons v2

[Unicons](https://github.com/realmorg/unicons) is rebuilt on REALM v2. Instead of one file per icon, a single `<u-icon>` element renders any of about 50,000 icons in 31 sets, and each set loads once, only when a page uses it.

## How to start

Add two lines to any HTML page:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js"></script>
```

Then write a `<custom-element>` in the page, or put components in their own files and load them with `<import-element>`. Pin an exact version in production.

- [Quick start](/docs/quick-start/)
- [Tutorial](/docs/tutorial/)
- [Examples](/examples/)
- [Migrating from v1](/docs/migrating-from-v1/), with a tag-by-tag cheat sheet

v2 is in alpha. Bug reports and feedback are welcome on [GitHub](https://github.com/realmorg/realm).


---

# Project is under maintenance mode

Source: http://realm.js.org/blog/project-is-under-maintenance-mode/

*5 June 2025 · Ribhararnus Pracutian*

> This post is about REALM v1. REALM v2 came out in October 2026. Read [REALM is dead, long live REALM](/blog/realm-v2/) and [Migrating from v1](/docs/migrating-from-v1/).

## Realm Framework Update: Transition to Maintenance and Future Guidance

Thank you to everyone who has shown interest in Realm Framework over the years. While community involvement has been limited, the project has benefited greatly from the feedback, and encouragement. That said, the bulk of the development, maintenance, and decision-making has been carried out solely by myself since its inception.

As of 2025, Realm Framework has officially transitioned into **"maintenance mode."** This decision is based on several key developments:

1. **Unstable Foundations in Web Standards**  
   The core technologies that Realm depends on—namely the Shadow DOM and Web Component APIs—have undergone frequent and unpredictable changes across browsers. These shifts have made maintaining stable, cross-browser behavior extremely difficult and time-consuming for a solo maintainer.

2. **The Shifting Ecosystem**  
   The web development landscape has evolved significantly. Libraries like [Shoelace](https://github.com/shoelace-style/shoelace), which deliver well-designed, standard-compliant components, have emerged as leading alternatives. Their active communities and robust toolsets offer a more sustainable future for modern projects.

3. **Lack of Real-World Usage**  
   Since Realm Framework is no longer being used in any of my active production applications, and with no other contributors involved, it has become impractical to continue innovating or expanding its features. The absence of field usage removes the real-world feedback that is vital for iterative improvement.

---

### What "Maintenance Mode" Means

No breaking changes or major new features will be introduced going forward. My goal is to preserve stability and reduce disruption for existing users. While the project will stay online and usable, only occasional bug fixes and small updates will be made when necessary.

---

### If You're Starting a New Project

If you're starting fresh, **Realm Framework is not recommended**. The combination of evolving platform standards, lack of contributor involvement, and an outdated foundation makes Realm a less reliable choice for future-proof development.

Instead, I suggest exploring [Shoelace](https://github.com/shoelace-style/shoelace), which provides:

- Compatibility with any frontend framework 🧩
- Complete theming and customization via CSS 🎨
- An official dark mode 🌛
- A strong emphasis on accessibility ♿️
- A modern, actively maintained codebase

Shoelace is better aligned with current web standards and enjoys consistent community and developer support.

---

### Ending Donations and Support Funding

Since the project has always been a one-person effort, and with development now slowed to essential upkeep only, continuing to accept donations no longer feels appropriate. All recurring contributions have been canceled, and no new donations will be accepted. A small reserve remains for critical patches or occasional bug bounties.

---

### In Gratitude

Although this has been a mostly solo project, I'm deeply thankful for those who used, shared, or supported Realm Framework in any way. It has been an insightful and rewarding journey.

Wishing you great success in your development journey,  
**Realm Framework (Maintained by a solo developer)**


---

# Introducing Unicons by Realm

Source: http://realm.js.org/blog/universal-web-component-icons/

*29 September 2023 · Ribhararnus Pracutian*

> This post is about REALM v1 and Unicons v1. Its code uses v1 syntax, and unicons.realm.codes is offline. See [Migrating from v1](/docs/migrating-from-v1/) and [realmorg/unicons](https://github.com/realmorg/unicons).

The web is a visual medium. Icons are a big part of how we communicate. They’re also a big part of how we interact with the web. Icons are everywhere, and they’re used for everything.

All frameworks have their own icon set, but they’re all different. To import them, you have to use a different syntax. And they’re all different sizes, so you have to use a different syntax to import them.

So, we decided to create a universal icon set that works across all frameworks. It’s called Unicons, stands for Universal Web Component Icons, is a collection of icons ported from [React Icons](https://react-icons.github.io/react-icons/) to be used as web components. It's designed to be used accross the web, so you can use icons from any website not limited to framework or library.

The website can be found at [realm.js.org/unicons](/unicons/).

## Installation

You can use unicons in your project by installing Realm. And then you can copy the icon you want to use from [https://github.com/realmorg/unicons](https://github.com/realmorg/unicons).

```html
<!DOCTYPE html>
<html>
  <head>
    ...
    <script
      src="https://cdn.jsdelivr.net/npm/@realmorg/realm/dist/realm.production.min.js"
      type="module"></script>
    <link
      href="https://cdn.jsdelivr.net/npm/@realmorg/realm/dist/realm.min.css"
      rel="stylesheet" />
    ...
  </head>

  <body>
    <import-element
      from="https://unicons.realm.codes/ICON-NAME.html"></import-element>

    <!-- You can use icon custom element's tag in your web page or framework -->
    <icon-name-element></icon-name-element>
  </body>
</html>
```

## Example #1

Basic usage of Unicons, you can copy the icon you want to use from [https://github.com/realmorg/unicons](https://github.com/realmorg/unicons).

```html
<import-element
  from="https://unicons.realm.codes/fc-landscape.html"></import-element>
<icon-fc-landscape></icon-fc-landscape>
```

## Example #2

Import icon inside a custom element.

```html
<custom-element name="save-button">
  <template>
    <style>
      :host {
        display: inline-block;
      }
      button {
        display: inline-flex;
        place-items: center;
        padding: 8px 12px;
        background: teal;
        font-weight: 900;
        border: 0;
        border-radius: 4px;
        cursor: pointer;
        gap: 4px;
      }
    </style>
    <button>
      <import-element
        from="https://unicons.realm.codes/fc-flash-on.html"></import-element>
      <icon-fc-flash-on size="20px"></icon-fc-flash-on>
      <span>
        <slot children></slot>
      </span>
    </button>
  </template>
</custom-element>

<save-button onclick="alert('Save mutation to API')">Save changes</save-button>
```

## Final words

The website is still in beta, so there are bug related with `import-element` network request, but overall, it's working as expected, if you don't import multiple icon (hundred of icons) in the same page.


---

# Initial Release 🎉

Source: http://realm.js.org/blog/initial-release/

*9 September 2023 · Ribhararnus Pracutian*

> This post is about REALM v1. Its code uses v1 syntax, which v2 does not support. See [Migrating from v1](/docs/migrating-from-v1/).

Realm is a new way to build web apps using native Web Components. With no bundler or compiler required, it offers a straightforward HTML framework that relies less on JavaScript dependencies.

After initial iteration, we are happy to announce that Realm is now available for public use. We are excited to see what you will build with it!

## Mindset

Realm is designed for indie-techpreunership, build an MVP as fast as possible, without worrying about the complexity of build process and tooling. We only need: HTML, CSS, maybe with a little bit of JavaScript.

We're so back to the basic, we're using HTML as our main language, we're using CSS as our main styling language, and we're using JavaScript (if it become complex and needed).

If you have a Browser and Text Editor, you can build your web app. Just install CDN to your HTML document, and you're ready to go.

## Features

There are several features that Realm offers:

- **No bundler or compiler required**. Realm is designed to be used without any bundler or compiler, it's live inside your HTML document.
- **Reactivity without JavaScript**. Realm is using HTML as its main language, so you can use HTML to define your custom element's state. We also offers a global state by default.
- **Reusability accross the web**. Realm is designed to be used accross the web, so you can use any pre-defined or existing custom element from any website (by enabling CORS).

There's more features that Realm offers, please check our [Documentations](/docs/) to learn more.

## Examples

```html
<custom-element name="initial-release-element">
  <element-attr name="message" type="string">Default message</element-attr>
  <template>
    <div>
      Announcement:
      <slot name="@message"></slot>
    </div>
  </template>
</custom-element>

<initial-release-element message="Initial Release 🎉"></initial-release-element>
```

As you can see we can define a native custom element using `<custom-element>` tag, and we can define its attribute using `<element-attr>` tag, and finally we're render our custom element inside `<template>` tag.

That's so simple right?, we don't need JavaScript to define our custom element, we don't need to use any bundler or compiler, we're just using simple HTML tag to define our custom element.

## Give it a try!

Please give it a try and let us know what you think! We are looking forward to your feedback.


---

# REALM

Source: http://realm.js.org/

<section class="hero">
  <realm-logo size="72"></realm-logo>
  <h1>The HTML framework for shipping MVPs</h1>
  <p class="lead">REALM turns a <code>&lt;custom-element&gt;</code> tag into a working web component in the browser. Write the script, style and markup in plain HTML, load REALM from a CDN and open the file. There is no build step.</p>
  <div class="actions">
    <a class="action primary" href="/docs/quick-start/">Get started <u-icon name="arrow-right"></u-icon></a>
    <a class="action outline" href="/examples/"><u-icon name="layout-grid"></u-icon> Examples</a>
  </div>
</section>

<section class="home-section major" aria-labelledby="write-a-component">
<header class="section-head">
<span class="section-icon"><u-icon name="code-xml" aria-hidden="true"></u-icon></span>
<h2 id="write-a-component">Write a web component in plain HTML</h2>
<p class="section-lead">A REALM component is one <code>&lt;custom-element&gt;</code> tag that holds a script, a style and markup. Values appear through native <code>&lt;slot&gt;</code> tags and events use plain <code>onclick</code>. The code on the left is the whole page.</p>
</header>

```html live split
<custom-element name="click-counter">
  <script type="realm">
    const props = defineProps({ step: prop.number().int().min(1).default(1) });

    const counter = useState({
      count: 0,
      get unit() {
        return this.count === 1 ? "time" : "times";
      },
    });

    function increment() {
      counter.count += props.step;
    }

    function reset() {
      counter.count = 0;
    }
  </script>

  <style type="realm">
    :host {
      display: inline-flex;
      gap: calc(var(--spacing) * 2);
    }
  </style>

  <ui-button onclick="increment()">Clicked <slot name="#counter.count"></slot> <slot name="#counter.unit"></slot></ui-button>
  <ui-button variant="outline" onclick="reset()">Reset</ui-button>
</custom-element>

<click-counter></click-counter>
<click-counter step="5"></click-counter>
```

</section>

<section class="home-section" aria-labelledby="state-and-data">
<header class="section-head">
<span class="section-icon"><u-icon name="mouse-pointer-click" aria-hidden="true"></u-icon></span>
<h2 id="state-and-data">State, lists, data and forms</h2>
<p class="section-lead"><code>useState</code> returns a plain object. Change it and only the slots and attributes that read it update. Requests, forms and component files work through HTML attributes and tags.</p>
</header>
<ui-tabs value="state" class="demo-tabs">
<ui-tabs-list aria-label="Examples">
<ui-tabs-trigger value="state"><u-icon name="list-checks" aria-hidden="true"></u-icon>State</ui-tabs-trigger>
<ui-tabs-trigger value="fetch"><u-icon name="cloud-download" aria-hidden="true"></u-icon>Fetch</ui-tabs-trigger>
<ui-tabs-trigger value="forms"><u-icon name="send" aria-hidden="true"></u-icon>Forms</ui-tabs-trigger>
<ui-tabs-trigger value="files"><u-icon name="file-code-2" aria-hidden="true"></u-icon>Files</ui-tabs-trigger>
</ui-tabs-list>
<ui-tabs-content value="state">
<p class="demo-note"><code>repeat</code> renders one row per item. Getters such as <code>left</code> recompute when the data they read changes.</p>

```html live split
<custom-element name="todo-list">
  <script type="realm">
    const todos = useState({
      items: [
        { id: 1, text: "Write a component", done: true },
        { id: 2, text: "Ship the MVP", done: false },
      ],
      draft: "",
      get left() {
        return `${this.items.filter((item) => !item.done).length} left`;
      },
    });

    function add(event) {
      event.preventDefault();
      const text = todos.draft.trim();
      if (!text) return;
      todos.items.push({ id: Date.now(), text, done: false });
      todos.draft = "";
    }

    function updateDraft(field) {
      todos.draft = field.value;
    }

    function toggle(item) {
      item.done = !item.done;
    }

    function remove(item) {
      todos.items.splice(todos.items.indexOf(item), 1);
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      width: min(calc(var(--spacing) * 96), 100%);
    }
    form {
      display: flex;
      gap: calc(var(--spacing) * 2);
    }
    form ui-input {
      flex: 1;
    }
    ul {
      margin: 0;
      padding: 0;
      list-style: none;
    }
    li {
      display: flex;
      align-items: center;
      gap: calc(var(--spacing) * 3);
      padding: calc(var(--spacing) * 1) 0;
    }
    li span {
      flex: 1;
    }
    li[data-done] span {
      color: var(--muted-foreground);
      text-decoration: line-through;
    }
    small {
      color: var(--muted-foreground);
    }
  </style>

  <form onsubmit="add(event)">
    <ui-input aria-label="New todo" placeholder="What needs doing?" _value="#todos.draft" oninput="updateDraft(this)"></ui-input>
    <ui-button type="submit">Add</ui-button>
  </form>
  <ul>
    <li repeat="#todos.items" as="item" key="id" _data-done="#item.done">
      <ui-checkbox _aria-label="#item.text" _checked="#item.done" onchange="toggle(item)"></ui-checkbox>
      <span><slot name="#item.text"></slot></span>
      <ui-button variant="ghost" size="sm" onclick="remove(item)">Remove</ui-button>
    </li>
  </ul>
  <small><slot name="#todos.left"></slot></small>
</custom-element>

<todo-list></todo-list>
```

</ui-tabs-content>
<ui-tabs-content value="fetch">
<p class="demo-note"><code>fetch</code> names the URL, <code>into</code> names the state that receives the JSON and <code>busy</code> tracks loading. The script only declares the state.</p>

```html live split
<custom-element name="book-shelf">
  <script type="realm">
    const shelf = useState({ books: [], loading: false });
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 3);
      justify-items: start;
      width: min(calc(var(--spacing) * 96), 100%);
    }
    ul {
      margin: 0;
      padding-left: calc(var(--spacing) * 5);
    }
    span {
      color: var(--muted-foreground);
    }
  </style>

  <ui-button fetch="/demos/books.json" into="#shelf.books" busy="#shelf.loading" _disabled="#shelf.loading">Load books</ui-button>
  <is-visible when="#shelf.loading"><ui-spinner></ui-spinner></is-visible>
  <ul>
    <li repeat="#shelf.books" as="book" key="id"><slot name="#book.title"></slot> <span>by <slot name="#book.author"></slot></span></li>
  </ul>
</custom-element>

<book-shelf></book-shelf>
```

</ui-tabs-content>
<ui-tabs-content value="forms">
<p class="demo-note">REALM components are form fields. They submit, reset and validate with their <code>&lt;form&gt;</code>, so <code>FormData</code> is all you need.</p>

```html live split
<custom-element name="signup-form">
  <script type="realm">
    const result = useState({ text: "Submit the form to see what it sends." });

    function submit(event) {
      event.preventDefault();
      const data = Object.fromEntries(new FormData(event.target));
      result.text = JSON.stringify(data, null, 2);
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      width: min(calc(var(--spacing) * 96), 100%);
    }
    form {
      display: grid;
      gap: calc(var(--spacing) * 4);
    }
    pre {
      margin: 0;
      padding: calc(var(--spacing) * 3);
      border-radius: var(--radius-md);
      background: var(--muted);
      font-size: var(--text-sm);
    }
  </style>

  <form onsubmit="submit(event)">
    <ui-field>
      <ui-label for="signup-email">Email</ui-label>
      <ui-input id="signup-email" name="email" type="email" required placeholder="you@example.com"></ui-input>
    </ui-field>
    <ui-select name="plan" aria-label="Plan">
      <option value="free">Free</option>
      <option value="team">Team</option>
    </ui-select>
    <ui-switch name="updates" checked>Send me product updates</ui-switch>
    <ui-button type="submit">Sign up</ui-button>
  </form>
  <pre><slot name="#result.text"></slot></pre>
</custom-element>

<signup-form></signup-form>
```

</ui-tabs-content>
<ui-tabs-content value="files">
<p class="demo-note">Keep each component in its own HTML file and load it with <code>&lt;import-element&gt;</code>. The file is fetched once and parsed, never run as a script. Open the <code>profile-card.html</code> tab to see it.</p>

```html live split
<import-element from="/demos/profile-card.html"></import-element>

<div class="demo-narrow demo-stack">
  <profile-card name="Ada Lovelace" job="Mathematician"></profile-card>
  <profile-card name="Alan Turing" job="Computer scientist"></profile-card>
</div>
```

</ui-tabs-content>
</ui-tabs>
</section>

<section class="home-section major" aria-labelledby="server-rendered-html">
<header class="section-head">
<span class="section-icon"><u-icon name="server" aria-hidden="true"></u-icon></span>
<h2 id="server-rendered-html">Server-rendered HTML that search engines can read</h2>
<p class="section-lead">Your server sends the page as ordinary HTML, so titles, text, links and meta tags are all in the first response. Search engines and AI crawlers index it without running JavaScript, and REALM upgrades the custom tags into components in the browser. There is no hydration step and no JavaScript server to run.</p>
</header>
<ul class="backends" aria-label="Server-side stacks">
<li><u-icon set="si" name="php" aria-hidden="true"></u-icon>PHP</li>
<li><u-icon set="si" name="rubyonrails" aria-hidden="true"></u-icon>Rails</li>
<li><u-icon set="si" name="django" aria-hidden="true"></u-icon>Django</li>
<li><u-icon set="si" name="go" aria-hidden="true"></u-icon>Go</li>
<li><u-icon set="si" name="nodedotjs" aria-hidden="true"></u-icon>Node.js</li>
<li><u-icon set="si" name="hugo" aria-hidden="true"></u-icon>Hugo</li>
</ul>
<div class="ssr">
<figure class="ssr-pane">
<figcaption>Your server template</figcaption>
<ui-tabs value="php">
<ui-tabs-list aria-label="Server templates">
<ui-tabs-trigger value="php">faq.php</ui-tabs-trigger>
<ui-tabs-trigger value="erb">faq.html.erb</ui-tabs-trigger>
<ui-tabs-trigger value="django">faq.html</ui-tabs-trigger>
<ui-tabs-trigger value="go">faq.tmpl</ui-tabs-trigger>
</ui-tabs-list>
<ui-tabs-content value="php">

```html
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/components/accordion.html"></import-element>

<ui-accordion>
  <?php foreach ($faqs as $faq): ?>
    <ui-accordion-item>
      <ui-accordion-trigger><?= htmlspecialchars($faq->question) ?></ui-accordion-trigger>
      <ui-accordion-content><?= htmlspecialchars($faq->answer) ?></ui-accordion-content>
    </ui-accordion-item>
  <?php endforeach ?>
</ui-accordion>
```

</ui-tabs-content>
<ui-tabs-content value="erb">

```html
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/components/accordion.html"></import-element>

<ui-accordion>
  <% @faqs.each do |faq| %>
    <ui-accordion-item>
      <ui-accordion-trigger><%= faq.question %></ui-accordion-trigger>
      <ui-accordion-content><%= faq.answer %></ui-accordion-content>
    </ui-accordion-item>
  <% end %>
</ui-accordion>
```

</ui-tabs-content>
<ui-tabs-content value="django">

```html
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/components/accordion.html"></import-element>

<ui-accordion>
  {% for faq in faqs %}
    <ui-accordion-item>
      <ui-accordion-trigger>{{ faq.question }}</ui-accordion-trigger>
      <ui-accordion-content>{{ faq.answer }}</ui-accordion-content>
    </ui-accordion-item>
  {% endfor %}
</ui-accordion>
```

</ui-tabs-content>
<ui-tabs-content value="go">

```html
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/components/accordion.html"></import-element>

<ui-accordion>
  {{range .FAQs}}
    <ui-accordion-item>
      <ui-accordion-trigger>{{.Question}}</ui-accordion-trigger>
      <ui-accordion-content>{{.Answer}}</ui-accordion-content>
    </ui-accordion-item>
  {{end}}
</ui-accordion>
```

</ui-tabs-content>
</ui-tabs>
</figure>
<figure class="ssr-pane">
<figcaption>What the browser shows</figcaption>

```html live
<div class="demo-medium">
  <ui-accordion>
    <ui-accordion-item open>
      <ui-accordion-trigger>Does REALM need a build step?</ui-accordion-trigger>
      <ui-accordion-content>No. Load it from a CDN and write each component in an HTML file.</ui-accordion-content>
    </ui-accordion-item>
    <ui-accordion-item>
      <ui-accordion-trigger>Can search engines read these answers?</ui-accordion-trigger>
      <ui-accordion-content>Yes. Every question and answer is text in the page's HTML. The accordion only adds opening and closing.</ui-accordion-content>
    </ui-accordion-item>
    <ui-accordion-item>
      <ui-accordion-trigger>Which servers does it work with?</ui-accordion-trigger>
      <ui-accordion-content>Any server that sends HTML: PHP, Rails, Django, Go, Node.js or a static site generator.</ui-accordion-content>
    </ui-accordion-item>
  </ui-accordion>
</div>
```

</figure>
</div>
<div class="seo">
<figure class="ssr-pane">
<figcaption>What a crawler receives</figcaption>

```html
<head>
  <title>FAQ · Acme</title>
  <meta name="description" content="Answers about Acme.">
</head>
<body>
  <ui-accordion>
    <ui-accordion-item>
      <ui-accordion-trigger>Does REALM need a build step?</ui-accordion-trigger>
      <ui-accordion-content>No. Load it from a CDN and write each component in an HTML file.</ui-accordion-content>
    </ui-accordion-item>
    <ui-accordion-item>
      <ui-accordion-trigger>Can search engines read these answers?</ui-accordion-trigger>
      <ui-accordion-content>Yes. Every question and answer is text in the page's HTML.</ui-accordion-content>
    </ui-accordion-item>
  </ui-accordion>
</body>
```

</figure>
<ul class="seo-points">
<li><u-icon name="search" aria-hidden="true"></u-icon><strong>Indexed from the first response</strong><span>Compound parts hold their content as ordinary child elements, so every question and answer is in the HTML a search engine fetches.</span></li>
<li><u-icon name="bot" aria-hidden="true"></u-icon><strong>Readable by AI crawlers</strong><span>Many AI crawlers do not run JavaScript. They read the same text, because it never depended on a script.</span></li>
<li><u-icon name="layers" aria-hidden="true"></u-icon><strong>Nothing to hydrate</strong><span>The server's markup is the final markup. REALM attaches behaviour to it in place, with no second render and no state payload.</span></li>
<li><u-icon name="share-2" aria-hidden="true"></u-icon><strong>Link previews from your server</strong><span>The title, description and Open Graph tags are server output, so shared links unfurl with the right card.</span></li>
</ul>
</div>
<p class="ssr-note"><u-icon name="info" aria-hidden="true"></u-icon><span>Put content in compound parts and search engines index it. What a component draws inside its own shadow root is not in the HTML, because REALM does not output Declarative Shadow DOM.</span></p>
</section>

<section class="home-section" aria-labelledby="ui-kit">
<header class="section-head">
<span class="section-icon"><u-icon name="blocks" aria-hidden="true"></u-icon></span>
<h2 id="ui-kit">Sixty UI components and 50,939 icons</h2>
<p class="section-lead">REALM UI has about sixty accessible <code>ui-*</code> components: buttons, forms, dialogs, menus, tabs, tables and charts. Import one file and use the tags. Dark mode and theming come from CSS variables.</p>
</header>

```html live split
<div class="demo-narrow">
  <ui-card>
    <ui-card-header>
      <ui-card-title>Launch your MVP</ui-card-title>
      <ui-card-description>Every control here is a ui-* tag.</ui-card-description>
      <ui-card-action><ui-badge variant="secondary">Beta</ui-badge></ui-card-action>
    </ui-card-header>
    <ui-card-content class="demo-stack">
      <ui-field>
        <ui-label for="launch-name">Project name</ui-label>
        <ui-input id="launch-name" placeholder="my-first-mvp"></ui-input>
      </ui-field>
      <ui-switch checked>Email me when it is live</ui-switch>
    </ui-card-content>
    <ui-card-footer justify="between">
      <ui-button variant="outline">Cancel</ui-button>
      <ui-button onclick="document.dispatchEvent(new CustomEvent('toast', { detail: { title: 'Launched', description: 'Your MVP is live.' } }))">Launch</ui-button>
    </ui-card-footer>
  </ui-card>
</div>
```

<div class="icon-strip" aria-labelledby="icons">
<div>
<h3 id="icons">Icons from 31 sets in one tag</h3>
<p>Unicons gives you 50,939 icons through <code>&lt;u-icon name="heart" set="tb"&gt;</code>. Each page downloads only the icons it uses. <a href="/unicons/">Browse the catalog <u-icon name="arrow-right" aria-hidden="true"></u-icon></a></p>
</div>
<div class="icon-row">
<u-icon name="heart" size="32"></u-icon>
<u-icon set="tb" name="heart-filled" size="32" color="crimson"></u-icon>
<u-icon set="pi" name="heart" size="32"></u-icon>
<u-icon set="fa6" name="rocket" size="32"></u-icon>
<u-icon set="bi" name="rocket" size="32" color="rebeccapurple"></u-icon>
<u-icon name="rocket" size="32" stroke-width="1"></u-icon>
</div>
</div>
</section>

<section class="home-section" aria-labelledby="platform">
<header class="section-head">
<span class="section-icon"><u-icon name="globe" aria-hidden="true"></u-icon></span>
<h2 id="platform">Built on browser features, with no dependencies</h2>
<p class="section-lead">The REALM runtime is 16 KB gzipped and depends on nothing. Each UI component wraps a feature the browser already ships, so focus, layering, keyboard and forms behave like built-in elements. Try them.</p>
</header>
<div class="platform-grid">
<figure class="platform-tile">
<div class="platform-stage">
<ui-dialog>
  <ui-dialog-trigger><ui-button variant="outline">Open dialog</ui-button></ui-dialog-trigger>
  <ui-dialog-header>
    <ui-dialog-title>A native dialog</ui-dialog-title>
    <ui-dialog-description>Press Escape or click outside to close it. Focus goes back to the button.</ui-dialog-description>
  </ui-dialog-header>
  <ui-dialog-footer>
    <ui-dialog-close><ui-button>Close</ui-button></ui-dialog-close>
  </ui-dialog-footer>
</ui-dialog>
</div>
<figcaption>
<p class="platform-map"><code>&lt;ui-dialog&gt;</code><u-icon name="arrow-right" role="img" aria-label="uses"></u-icon><code>&lt;dialog&gt;</code></p>
<p>Top layer, focus moves in, Escape closes.</p>
</figcaption>
</figure>
<figure class="platform-tile">
<div class="platform-stage">
<ui-popover>
  <ui-popover-trigger><ui-button variant="outline">Open popover</ui-button></ui-popover-trigger>
  <ui-popover-content width="56">Click anywhere outside to close it.</ui-popover-content>
</ui-popover>
</div>
<figcaption>
<p class="platform-map"><code>&lt;ui-popover&gt;</code><u-icon name="arrow-right" role="img" aria-label="uses"></u-icon><code>popover</code></p>
<p>The Popover API: no z-index fights, light dismiss.</p>
</figcaption>
</figure>
<figure class="platform-tile">
<div class="platform-stage">
<form class="platform-form" onsubmit="event.preventDefault(); this.reset()">
  <ui-input name="email" type="email" required placeholder="you@example.com" aria-label="Email"></ui-input>
  <ui-button type="submit">Send</ui-button>
</form>
</div>
<figcaption>
<p class="platform-map"><code>&lt;ui-input&gt;</code><u-icon name="arrow-right" role="img" aria-label="uses"></u-icon><code>ElementInternals</code></p>
<p>Submit it empty and the browser checks it.</p>
</figcaption>
</figure>
<figure class="platform-tile">
<div class="platform-stage">
<ui-select aria-label="Engine">
  <option value="blink">Chromium</option>
  <option value="gecko">Firefox</option>
  <option value="webkit">WebKit</option>
</ui-select>
</div>
<figcaption>
<p class="platform-map"><code>&lt;ui-select&gt;</code><u-icon name="arrow-right" role="img" aria-label="uses"></u-icon><code>&lt;select&gt;</code></p>
<p>Plain <code>&lt;option&gt;</code> tags and the native picker.</p>
</figcaption>
</figure>
<figure class="platform-tile">
<div class="platform-stage">
<ui-toggle-group type="multiple" value="bold" aria-label="Text formatting">
  <ui-toggle value="bold" variant="outline" aria-label="Bold"><u-icon name="bold"></u-icon></ui-toggle>
  <ui-toggle value="italic" variant="outline" aria-label="Italic"><u-icon name="italic"></u-icon></ui-toggle>
  <ui-toggle value="underline" variant="outline" aria-label="Underline"><u-icon name="underline"></u-icon></ui-toggle>
</ui-toggle-group>
</div>
<figcaption>
<p class="platform-map"><code>&lt;ui-toggle-group&gt;</code><u-icon name="arrow-right" role="img" aria-label="uses"></u-icon><code>focusgroup</code></p>
<p>Tab in once, then arrow keys move between buttons.</p>
</figcaption>
</figure>
<figure class="platform-tile">
<div class="platform-stage">
<ui-switch checked>Email updates</ui-switch>
</div>
<figcaption>
<p class="platform-map"><code>&lt;ui-switch&gt;</code><u-icon name="arrow-right" role="img" aria-label="uses"></u-icon><code>:state(attr-checked)</code></p>
<p>CustomStateSet: style it like a native pseudo-class.</p>
</figcaption>
</figure>
</div>
<dl class="facts">
<div><dt><u-icon name="file-archive" aria-hidden="true"></u-icon>16 KB</dt><dd>runtime, gzipped</dd></div>
<div><dt><u-icon name="package" aria-hidden="true"></u-icon>0</dt><dd>dependencies</dd></div>
<div><dt><u-icon name="shield-check" aria-hidden="true"></u-icon>100%</dt><dd>test coverage</dd></div>
<div class="facts-browsers">
<dt>
<ul class="engines" aria-label="Supported browsers">
<li><u-icon set="ri" name="chrome-fill" aria-hidden="true"></u-icon>Chrome</li>
<li><u-icon set="ri" name="edge-new-fill" aria-hidden="true"></u-icon>Edge</li>
<li><u-icon set="ri" name="firefox-browser-fill" aria-hidden="true"></u-icon>Firefox</li>
<li><u-icon set="ri" name="safari-fill" aria-hidden="true"></u-icon>Safari</li>
</ul>
</dt>
<dd>Tested in every major browser and engine. <a href="/docs/browser-support/">Browser support</a></dd>
</div>
</dl>
</section>

<section class="home-section major" aria-labelledby="coding-assistants">
<header class="section-head">
<span class="section-icon"><u-icon name="bot" aria-hidden="true"></u-icon></span>
<h2 id="coding-assistants">Build with ChatGPT, Claude or Gemini</h2>
<p class="section-lead">A REALM component is one HTML file with native tags, a script and a style. There is no JSX and no compiled output for a model to reason about, and the REALM Agent Skill gives your coding assistant the rules.</p>
</header>
<div class="assist">
<div class="assist-start">
<ul class="assistants" aria-label="Coding assistants">
<li><u-icon set="ri" name="openai-fill" aria-hidden="true"></u-icon>ChatGPT</li>
<li><u-icon set="ri" name="claude-fill" aria-hidden="true"></u-icon>Claude</li>
<li><u-icon set="ri" name="gemini-fill" aria-hidden="true"></u-icon>Gemini</li>
</ul>
<div class="session" role="group" aria-label="Example session">
<p><span class="session-mark" aria-hidden="true">$</span><code>npx skills add realmorg/realm</code></p>
<p class="session-note"><span class="session-mark" aria-hidden="true">#</span><span>installs the REALM Agent Skill from the realmorg/realm repository on GitHub, or <a href="/skills/realm.zip" download>download realm.zip</a></span></p>
<p class="session-prompt"><span class="session-mark" aria-hidden="true">&gt;</span>Add a pricing table with REALM UI to index.html</p>
</div>
</div>
<ul class="assist-reasons">
<li><u-icon name="file-code-2" aria-hidden="true"></u-icon><strong>One file per component</strong><span>Script, style and markup sit together, so a model reads the whole component at once.</span></li>
<li><u-icon name="code-xml" aria-hidden="true"></u-icon><strong>Native tags, nothing compiled</strong><span>What the model writes is what the browser runs. View Source shows the same code.</span></li>
<li><u-icon name="file-text" aria-hidden="true"></u-icon><strong>Docs as Markdown</strong><span>Add <code>.md</code> to any docs address. <code>llms.txt</code> and <code>llms-full.txt</code> list every page.</span></li>
<li><u-icon name="list-checks" aria-hidden="true"></u-icon><strong>Rules with tests</strong><span>Behaviour is written as specs, and each rule has a test with the same name.</span></li>
</ul>
</div>
<p class="assist-caption">The kind of file that comes back. It is plain HTML and it runs right here.</p>

```html live split
<custom-element name="pricing-table">
  <script type="realm">
    const pricing = useState({
      yearly: false,
      get price() {
        return this.yearly ? "$190" : "$19";
      },
      get period() {
        return this.yearly ? "per year" : "per month";
      },
    });

    function setBilling(group) {
      pricing.yearly = group.value === "yearly";
    }
  </script>

  <style type="realm">
    :host {
      display: grid;
      gap: calc(var(--spacing) * 4);
      justify-items: center;
      width: min(calc(var(--spacing) * 128), 100%);
    }
    .plans {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(calc(var(--spacing) * 52), 1fr));
      gap: calc(var(--spacing) * 4);
      width: 100%;
    }
    strong {
      font-size: var(--text-3xl);
    }
    small {
      color: var(--muted-foreground);
    }
  </style>

  <ui-toggle-group value="monthly" aria-label="Billing" onchange="setBilling(this)">
    <ui-toggle value="monthly" variant="outline">Monthly</ui-toggle>
    <ui-toggle value="yearly" variant="outline">Yearly</ui-toggle>
  </ui-toggle-group>
  <div class="plans">
    <ui-card>
      <ui-card-header>
        <ui-card-title>Hobby</ui-card-title>
        <ui-card-description>One project, forever.</ui-card-description>
      </ui-card-header>
      <ui-card-content><strong>$0</strong> <small>free</small></ui-card-content>
      <ui-card-footer><ui-button variant="outline">Start free</ui-button></ui-card-footer>
    </ui-card>
    <ui-card>
      <ui-card-header>
        <ui-card-title>Team</ui-card-title>
        <ui-card-description>Unlimited projects.</ui-card-description>
        <ui-card-action><ui-badge>Popular</ui-badge></ui-card-action>
      </ui-card-header>
      <ui-card-content><strong><slot name="#pricing.price"></slot></strong> <small><slot name="#pricing.period"></slot></small></ui-card-content>
      <ui-card-footer><ui-button>Start a trial</ui-button></ui-card-footer>
    </ui-card>
  </div>
</custom-element>

<pricing-table></pricing-table>
```

<ul class="assist-links">
<li><a href="/docs/ai-skill/"><u-icon name="book-open" aria-hidden="true"></u-icon>Agent Skill guide</a></li>
<li><a href="/llms.txt"><u-icon name="file-text" aria-hidden="true"></u-icon>llms.txt</a></li>
<li><a href="/llms-full.txt"><u-icon name="files" aria-hidden="true"></u-icon>llms-full.txt</a></li>
<li><a href="https://github.com/realmorg/realm/tree/main/openspec/specs" rel="noopener" target="_blank"><u-icon name="github" aria-hidden="true"></u-icon>Specs on GitHub</a></li>
</ul>
</section>

<section class="home-section" aria-labelledby="examples">
<header class="section-head">
<span class="section-icon"><u-icon name="layout-grid" aria-hidden="true"></u-icon></span>
<h2 id="examples">Apps built with REALM</h2>
<p class="section-lead">Complete apps that run on this site. Each is a few HTML files and small JavaScript modules, so View Source shows the whole app.</p>
</header>
<div class="card-grid">
<a class="link-card" href="/examples/todo/"><u-icon name="list-todo"></u-icon><strong>Todo</strong><span>A persisted store, filters, keyed rows and inline editing.</span></a>
<a class="link-card" href="/examples/kanban/"><u-icon name="square-kanban"></u-icon><strong>Kanban board</strong><span>Native drag and drop, keyboard moves and a card editor.</span></a>
<a class="link-card" href="/examples/chess/"><u-icon name="crown"></u-icon><strong>Chess</strong><span>Legal moves, check and mate, and a computer opponent.</span></a>
<a class="link-card" href="/examples/dashboard/"><u-icon name="layout-dashboard"></u-icon><strong>Dashboard</strong><span>Sidebar, charts, a data table and a command palette.</span></a>
<a class="link-card" href="/examples/weather/"><u-icon name="cloud-sun"></u-icon><strong>Weather</strong><span>City search and a forecast loaded with fetch attributes.</span></a>
<a class="link-card" href="/examples/contacts/"><u-icon name="contact"></u-icon><strong>Contacts</strong><span>Create, edit and delete records over a JSON API.</span></a>
</div>
<p class="more"><a href="/examples/">All examples <u-icon name="arrow-right"></u-icon></a></p>
</section>

<section class="cta" aria-labelledby="start">
<h2 id="start">Start with one HTML file</h2>
<p>Add these two tags to any page. There is no npm install, no bundler and no config file, and View Source shows the code you wrote.</p>
<div class="cta-code">

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js"></script>
```

</div>
<div class="actions">
<a class="action primary" href="/docs/quick-start/">Read the quick start <u-icon name="arrow-right"></u-icon></a>
<a class="action outline" href="/docs/tutorial/"><u-icon name="book-open"></u-icon> Follow the tutorial</a>
</div>
</section>