Dialog
A modal dialog. Render Dialog.Trigger and Dialog.Content inside it. The root renders no element.
Built on bits-ui Dialog.
<Dialog bind:open> <Dialog.Trigger class="button">Open</Dialog.Trigger> <Dialog.Content class="w-full max-w-md"> <Dialog.Title>Rename</Dialog.Title> <Dialog.Description>Pick a new name.</Dialog.Description> <Dialog.Close /> </Dialog.Content></Dialog>- Composed from parts, so the trigger, the title, the body, and the footer are yours to arrange.
- One
open, bindable. Closing returns focus to the trigger. - Focus is trapped inside while open, Escape closes, and the page behind does not scroll, via bits-ui.
- The panel floats in a portal over a dimmed overlay. It is labeled by
Dialog.Titleand described byDialog.Description. Dialog.Contentcarries the panel styling only. Width is theclassyou pass.
Anatomy
Section titled “Anatomy”Every part is a property on Dialog. Dialog renders no element. The body and footer are your own markup inside Dialog.Content.
<Dialog> <Dialog.Trigger /> <Dialog.Content> <Dialog.Title /> <Dialog.Description /> <!-- body --> <!-- footer --> <Dialog.Close /> </Dialog.Content></Dialog>Two-way binding
Section titled “Two-way binding”bind:open on the root.
open: false
Code
<script lang="ts"> import { Dialog } from "@viamrobotics/prime-ui";
let open = $state(false);</script>
<div class="not-content"> <Dialog bind:open> <Dialog.Trigger class="button">Open dialog</Dialog.Trigger> <Dialog.Content class="w-full max-w-md"> <div class="flex items-start justify-between gap-4"> <Dialog.Title>Notifications</Dialog.Title> <Dialog.Close /> </div> <Dialog.Description class="mt-1">You will get an email when a machine goes offline.</Dialog.Description> </Dialog.Content> </Dialog>
<p class="mt-3 text-sm text-subtle-2">open: <code>{open}</code></p></div>Fully controlled
Section titled “Fully controlled”Pass bind:open a getter and a setter. The setter can decline a change. State & binding explains both modes.
open: false
Code
<script lang="ts"> import { Dialog } from "@viamrobotics/prime-ui";
let open = $state(false); let hasAcknowledged = $state(false);</script>
<div class="not-content"> <Dialog bind:open={ () => open, (next) => { if (next || hasAcknowledged) open = next; } } > <Dialog.Trigger class="button">Open dialog</Dialog.Trigger> <Dialog.Content class="w-full max-w-md"> <Dialog.Title>Terms of service</Dialog.Title> <Dialog.Description class="mt-1"> The setter declines every close until the box is checked, so Escape and the overlay do nothing. </Dialog.Description> <label class="mt-4 flex items-center gap-2 text-sm"> <input type="checkbox" bind:checked={hasAcknowledged} /> I accept </label> <div class="mt-4 flex justify-end"> <button class="button" type="button" onclick={() => (open = false)} disabled={!hasAcknowledged}> Continue </button> </div> </Dialog.Content> </Dialog>
<p class="mt-3 text-sm text-subtle-2">open: <code>{open}</code></p></div>Body and footer
Section titled “Body and footer”Dialog.Content is a column flex container with a maximum height. Put a scrolling body between the header and the footer with min-h-0 overflow-y-auto, and the footer stays in view. Dialog.Close takes children and a class, so it can be a labeled secondary button.
Code
<script lang="ts"> import { Dialog, Field, Input, Label } from "@viamrobotics/prime-ui";
let open = $state(false); let name = $state("");</script>
<div class="not-content"> <Dialog bind:open> <Dialog.Trigger class="button">Rename</Dialog.Trigger> <Dialog.Content class="w-full max-w-md gap-4"> <div class="flex items-start justify-between gap-4"> <Dialog.Title>Rename machine</Dialog.Title> <Dialog.Close /> </div>
<div class="flex min-h-0 flex-col gap-3 overflow-y-auto"> <Dialog.Description>The new name shows everywhere the machine is listed.</Dialog.Description> <Field class="flex flex-col gap-1"> <Label>Name</Label> <Input bind:value={name} /> </Field> </div>
<div class="flex justify-end gap-2"> <Dialog.Close class="button" aria-label="Cancel">Cancel</Dialog.Close> <button class="button" type="button" onclick={() => (open = false)}>Save</button> </div> </Dialog.Content> </Dialog></div>Sizing
Section titled “Sizing”Dialog.Content has no width of its own. Set one with class, the same as any other part.
<Dialog.Content class="w-full max-w-sm">…</Dialog.Content><Dialog.Content class="w-full max-w-md">…</Dialog.Content><Dialog.Content class="w-full max-w-2xl">…</Dialog.Content>Widths
Migrating from prime-core
Section titled “Migrating from prime-core”A prime-core Dialog took a size. Here the width is a class on Dialog.Content.
prime-core size |
Class on Dialog.Content |
|---|---|
small |
max-w-[25rem] |
medium |
max-w-[37.5rem] |
large |
max-w-[50rem] |
extra-large |
max-w-[60rem] |
Pair each with w-full so the panel fills the width up to that limit.
Styling
Section titled “Styling”Every part that renders an element takes class on that element. Dialog renders no element, so it takes no class. Dialog.Trigger is a real <button> with the shared focus ring and no other style, so add button or your own classes. Dialog.Close wears icon-button and shows a close icon labeled Close. Pass children to replace the icon and aria-label to replace the label. With children it wears no class of its own, so class="button" gives a text close the button class alone. bits-ui sets the data attributes in the table below. Dialog.Overlay wears z-overlay and Dialog.Content wears z-dialog, the shadow-dialog token, and rounded-sm; see z layers.
| Part | Attribute | Value |
|---|---|---|
Trigger |
data-state |
open or closed |
Overlay |
data-state |
open or closed |
Content |
data-state |
open or closed |
The overlay is part of Dialog.Content and takes no class of its own.
Keyboard
Section titled “Keyboard”| Key | Action |
|---|---|
| Enter / Space | On the trigger, opens the dialog. |
| Escape | Closes the dialog and returns focus to the trigger. |
| Tab / Shift + Tab | Cycles focus inside the dialog, wrapping at either end. |
| Prop | Type | Default | Description |
|---|---|---|---|
bind:open | boolean | Whether the dialog is open. Two-way bindable. | |
children | Snippet | The Dialog.* parts. |
Dialog.Close
A button that closes its Dialog. It renders a close icon by default, labeled
Close, and wears icon-button only then. Pass children to replace the icon, and aria-label to
replace the label.
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. |
Plus everything in HTMLButtonAttributes, spread onto the element.
Dialog.Content
The panel of a Dialog, rendered in a portal above a dimmed overlay.
It carries the panel styling only. Set the width with class, such as w-full max-w-md. Focus is trapped inside
while it is open, Escape closes it, focus returns to the trigger, and the page behind does not scroll.
Takes extraClasses, children, portal, ...restProps }: Props as its props.
Dialog.Description
The supporting text of a Dialog, rendered as a p. The dialog is described by it.
Takes extraClasses, children, ...restProps }: Props as its props.
Dialog.Title
The heading of a Dialog, rendered as an h2. The dialog is labeled by it.
Takes extraClasses, children, ...restProps }: Props as its props.
Dialog.Trigger
The button that opens a Dialog. It carries no visual style of its own, so add button or another class.
Takes extraClasses, children, ...restProps }: Props as its props.