Overlays
Modal, alert and dropdown are native <dialog> and popover, opened from HTML. The runtime handles Esc, Back, focus return and scroll lock, and loads only on pages that contain an overlay.
Modal with @open and @close
@open="about-pragma" opens the overlay with that id and @close closes the one it sits in; neither needs a line of JS. <c-modal> takes id and title, a default slot and an actions slot. It closes on Esc, a click on the backdrop, the × button, any @close, and the browser's Back button.
routes/examples/overlays/_components/about-modal/about-modal.html
<div> <button type="button" class="btn" @open="about-pragma">What is pragma?</button> <c-modal id="about-pragma" title="What is pragma?"> <p>A framework for web apps written in native HTML, CSS and JavaScript, compiled and checked by a Rust CLI.</p> <button slot="actions" type="button" class="btn btn-primary" @close value="ok">Got it</button> </c-modal></div>
Live result
Alert with await confirm(id)
import { confirm } from 'pragma', then await confirm(id) opens the alert and resolves with the value of the @close button that was clicked, or 'cancel' on Esc and Back. <c-alert> is a <dialog role="alertdialog">, so a backdrop click does not dismiss it. For a destructive action, put autofocus on the safe button.
routes/examples/overlays/_components/delete-draft/delete-draft.html
<script> import { confirm } from 'pragma' let deleted = false let answer = '' const answerText = () => (answer ? `confirm() resolved '${answer}'` : 'confirm() not called yet') async function remove() { answer = await confirm('delete-draft') if (answer === 'ok') deleted = true } function restore() { deleted = false answer = '' }</script><div> <div class="draft-file"> <span class="draft-name" .is-gone="$deleted">draft-notes.md</span> <if $deleted> <button type="button" class="btn btn-small" @click="restore">Restore</button> </if> <else> <button type="button" class="btn btn-small btn-danger" @click="remove">Delete</button> </else> </div> <p class="draft-answer" role="status">{$answerText}</p> <c-alert id="delete-draft" title="Delete draft-notes.md?"> <p>The file is removed for good. There is no trash to restore it from.</p> <button slot="actions" type="button" class="btn" @close value="cancel" autofocus>Keep it</button> <button slot="actions" type="button" class="btn btn-danger" @close value="ok">Delete</button> </c-alert></div><style> [data-c="delete-draft"] { display: grid; gap: 0.75rem; width: 100%; max-width: 20rem; } .draft-file { display: flex; align-items: center; justify-content: space-between; gap: 1rem; padding: 0.5rem 0.5rem 0.5rem 1rem; border: 1px solid var(--color-line-strong); background: var(--color-surface); } .draft-name { color: var(--color-ink); font-family: var(--font-mono); font-size: 0.8125rem; } .draft-name.is-gone { color: var(--color-faint); text-decoration: line-through; } .draft-answer { min-height: 1lh; color: var(--color-faint); font-family: var(--font-mono); font-size: 0.75rem; }</style>
Live result
confirm() not called yet
Dropdown on the popover API
<c-dropdown> is a [popover] under its button, flipped above when there is no room below. It closes on an outside click, Esc, @close and Back, and it does not lock scroll. Items can combine @close with @click, and pass arguments: @click="sortBy('size')".
The label here is a dynamic prop, :label="$menuLabel": the dropdown has no script, so it reads the caller's derived function on every render.
routes/examples/overlays/_components/sort-menu/sort-menu.html
<script> const files = [ { name: 'router.js', size: 4120 }, { name: 'overlay.js', size: 2860 }, { name: 'state.js', size: 1310 }, { name: 'boot.js', size: 690 }, ] let key = 'name' let descending = false const menuLabel = () => 'Sort: ' + key + (descending ? ', desc' : ', asc') function sorted() { const rows = files .map(file => ({ ...file, label: (file.size / 1000).toFixed(1) + ' kB' })) .sort((left, right) => (key === 'size' ? left.size - right.size : left.name.localeCompare(right.name))) return descending ? rows.reverse() : rows } function sortBy(nextKey) { key = nextKey } function reverse() { descending = !descending }</script><div> <c-dropdown id="sort-menu" :label="$menuLabel"> <button type="button" @close @click="sortBy('name')">By name</button> <button type="button" @close @click="sortBy('size')">By size</button> <hr> <button type="button" @close @click="reverse">Reverse order</button> </c-dropdown> <ol class="sort-list"> <for file in $sorted key=file.name> <li class="sort-row"><span>{file.name}</span><span class="sort-size">{file.label}</span></li> </for> </ol></div><style> [data-c="sort-menu"] { display: grid; justify-items: start; gap: 0.75rem; width: 100%; max-width: 20rem; } .sort-list { width: 100%; border-top: 1px solid var(--color-line); font-family: var(--font-mono); font-size: 0.75rem; } .sort-row { display: flex; justify-content: space-between; padding: 0.5rem 0.25rem; border-bottom: 1px solid var(--color-line); color: var(--color-ink); } .sort-size { color: var(--color-muted); font-variant-numeric: tabular-nums; }</style>
Live result
- boot.js0.7 kB
- overlay.js2.9 kB
- router.js4.1 kB
- state.js1.3 kB
Stacking, open and close
Overlays stack: Discard with an edited name opens an alert on top of the modal. Each open overlay pushes a history entry, so Back closes only the top one. Focus returns to whatever opened each layer, and the page behind stops scrolling while a modal or alert is open, with the scrollbar gutter reserved only if there was a scrollbar.
From a script, open(id) and close(id) from 'pragma' do what @open and @close do. Open overlays only in response to a user action, and never keep "is open" in state: the <dialog> already knows.
routes/examples/overlays/_components/rename-project/rename-project.html
<script> import { open, close, confirm } from 'pragma' let name = 'minimart' let draft = '' const invalid = () => !draft.trim() function edit() { draft = name open('rename-modal') } function save() { name = draft.trim() close('rename-modal') } async function discard() { if (draft !== name && await confirm('discard-alert') !== 'ok') return close('rename-modal') }</script><div> <p class="rename-current">Project: <strong>{$name}</strong></p> <button type="button" class="btn" @click="edit">Rename project</button> <c-modal id="rename-modal" title="Rename project"> <label class="rename-field"> <span>Name</span> <input type="text" autocomplete="off" :model="$draft"> </label> <button slot="actions" type="button" class="btn" @click="discard">Discard</button> <button slot="actions" type="button" class="btn btn-primary" @click="save" :disabled="$invalid">Save</button> </c-modal> <c-alert id="discard-alert" title="Discard your changes?"> <p>The new name has not been saved.</p> <button slot="actions" type="button" class="btn" @close value="cancel" autofocus>Keep editing</button> <button slot="actions" type="button" class="btn btn-danger" @close value="ok">Discard</button> </c-alert></div><style> [data-c="rename-project"] { display: grid; justify-items: center; gap: 1rem; } .rename-current { color: var(--color-muted); font-family: var(--font-mono); font-size: 0.8125rem; } .rename-current strong { color: var(--color-ink); font-weight: 500; } .rename-field { display: grid; gap: 0.5rem; color: var(--color-muted); font-family: var(--font-mono); font-size: 0.75rem; } .rename-field input { height: 2.5rem; padding: 0 0.75rem; border: 1px solid var(--color-line-strong); background: var(--color-sunken); color: var(--color-ink); font-size: 0.875rem; } .rename-field input:focus-visible { outline-offset: 0; border-color: var(--color-accent); }</style>
Live result
Project: minimart
They are ordinary components
The three overlays ship in the starter as lib/components/modal, alert and dropdown: one .html each, with no script, that you can restyle like any other component. The behavior lives in core/overlay.js, which the build adds only to pages that contain a <dialog> or [popover].
- Do not create a
<dialog>or[popover]by hand, callshowModal(), usewindow.confirmorrole="menu", or importcore/overlay.jsyourself.
lib/components/modal/modal.html
<dialog class="dialog" :id="$id" :aria-label="$title"> <header class="mb-4 flex items-start justify-between gap-4"> <h2 class="text-lg font-semibold">{$title}</h2> <button type="button" class="rounded-lg p-1.5 text-muted transition-colors hover:text-ink" @close aria-label="Close"> <svg class="size-5" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" aria-hidden="true"><path d="M5 5l10 10M15 5L5 15"/></svg> </button> </header> <div class="text-sm text-muted"><slot></slot></div> <footer class="mt-6 flex justify-end gap-2"><slot name="actions"></slot></footer></dialog>
lib/components/alert/alert.html
<dialog class="dialog" role="alertdialog" :id="$id" :aria-label="$title"> <h2 class="text-lg font-semibold">{$title}</h2> <div class="mt-2 text-sm text-muted"><slot></slot></div> <footer class="mt-6 flex justify-end gap-2"><slot name="actions"></slot></footer></dialog>
lib/components/dropdown/dropdown.html
<div class="inline-flex"> <button type="button" class="btn" :data-open="$id" :popovertarget="$id"> <span>{$label}</span> <svg class="size-4 text-muted" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 6l4 4 4-4"/></svg> </button> <div popover :id="$id" class="min-w-48 border border-line bg-surface p-1 text-sm text-ink shadow-lg"> <slot></slot> </div></div><style> [data-c="dropdown"] [popover] > :is(a, button) { display: flex; width: 100%; align-items: center; gap: 0.5rem; padding: 0.5rem 0.75rem; text-align: start; cursor: pointer; } [data-c="dropdown"] [popover] > :is(a, button):is(:hover, :focus-visible) { background: var(--color-raised); outline: none; } [data-c="dropdown"] [popover] > hr { margin: 0.25rem 0; border-top: 1px solid var(--color-line); } @media (prefers-reduced-motion: no-preference) { [data-c="dropdown"] :popover-open { animation: dropdown-in 0.12s ease-out; } } @keyframes dropdown-in { from { opacity: 0; translate: 0 -0.25rem; } }</style>
Live result
Source only: the live versions are above.