Overlay · astro-ui · Dialog

DialogJS

Native <dialog> modal — platform focus trap, Esc, and backdrop.

Dialog is the first JS-required component — and deliberately so: it’s a thin styled wrapper over native <dialog>, so modality, backdrop, focus containment, Escape, and focus return all come from the platform. The component ships zero JS; your app calls showModal().

← All components

Features

Native <dialog>: focus trap + return, Esc, backdrop
title/description/footer slots with automatic aria wiring
Zero-JS close via method="dialog" forms
6 sizes, 8 variants
Built-in close button (showClose)
Backdrop-dismiss recipe in the docs

Usage

---
import { Dialog, Button } from "astro-ui";
---

<Button id="open">Open</Button>
<Dialog id="prefs">
  <h2 slot="title">Preferences</h2>
  <p slot="description">Device-only settings.</p>
  <form method="dialog"><Button>Close</Button></form>
</Dialog>
<script>
  document.getElementById("open")?.addEventListener("click", () =>
    document.getElementById("prefs")?.showModal());
</script>

Demos

Basic modal

<Button id="open">Open preferences</Button>
<Dialog id="prefs">
  <h2 slot="title">Preferences</h2>
  <p slot="description">These settings apply to this device only.</p>
  <div slot="footer">
<form method="dialog"><Button>Close</Button></form>
  </div>
</Dialog>
<script>
  document.getElementById("open")?.addEventListener("click", () =>
document.getElementById("prefs")?.showModal());
</script>

API

Props

Prop	Type	Default	Description
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	`"md"`	Width scale.
`id`	`string`	`recommended`	Enables automatic title/description aria wiring.
`showClose`	`boolean`	`true`	Native zero-JS close button.
`closeLabel`	`string`	`"Close dialog"`	Accessible label for it.
`ariaLabel`	`string`	`—`	Explicit name (skips aria-labelledby).
`variant`	`"inherit" \| "primary" \| … \| "info"`	`"inherit"`	Accent variant.
`class`	`string`	`—`	Merged via cn().

Slots

Slot	Description
`title`	Dialog heading (wired to aria-labelledby).
`description`	Subtitle (wired to aria-describedby).
`default`	Body content.
`footer`	Action row.

Accessibility

Implemented accessibility features — semantics, ARIA wiring, and keyboard behavior that ship with the component.

FAQ

How do I close it without JS?

A <form method="dialog"> button inside the dialog closes natively. Esc and the × button also work with zero app code.

Can clicking the backdrop close it?

Yes — recipe: dialog.addEventListener('click', (e) => { if (e.target === dialog) dialog.close(); }).

Changelog

Version history mentioning Dialog.

v0.1.0 — 2026-11-11

added

Overlay (8): Dialog, AlertDialog, Sheet, Tooltip, Popover, HoverCard, Lightbox, Menu.
Native-first interactive behavior: Dialog, AlertDialog, and Sheet on <dialog>; Accordion and Collapsible on <details>; Tabs, Menu, Tree, and Combobox with WAI-ARIA roles and scoped keyboard scripts.

fixed

Dialog, Lightbox, Sheet, and AlertDialog backdrops, Progress stripes, Carousel shadows, and Chart SVG shadows resolve through tokens instead of hard-coded colors.