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.

@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

What is pragma?

A framework for web apps written in native HTML, CSS and JavaScript, compiled and checked by a Rust CLI.

Open it, then press Back: the modal closes and the page stays put. Focus returns to the button.

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

draft-notes.md

confirm() not called yet

Delete draft-notes.md?

The file is removed for good. There is no trash to restore it from.

Try Keep it, Delete and Esc: the status line shows what the promise resolved to.

<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


  1. boot.js0.7 kB
  2. overlay.js2.9 kB
  3. router.js4.1 kB
  4. state.js1.3 kB
Keyboard: Tab to the button, Enter opens, Tab walks the items, Esc closes and returns focus.

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

Rename project

Discard your changes?

The new name has not been saved.

Edit the name, press Discard, then press Back: the alert closes and the modal stays.

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, call showModal(), use window.confirm or role="menu", or import core/overlay.js yourself.

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.

These are this site's copies, restyled to its tokens.