Open a focused task over the page.

A dialog gives a task its own space: share a link, edit a record, or collect a few details. It manages focus, Escape, outside presses, and returning to where you started.

<script setup lang="ts">
import {
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
import { XIcon } from "@lucide/vue"
</script>

<template>
  <Dialog>
    <DialogTrigger>Share</DialogTrigger>
    <DialogBackdrop />
    <DialogContent>
      <div data-slot="stack">
        <DialogTitle>Share link</DialogTitle>
        <DialogDescription
          >Anyone who has this link will be able to view
          this.</DialogDescription
        >
      </div>
      <Field>
        <FieldLabel>Link</FieldLabel>
        <Input defaultValue="https://example.com/project" readonly />
      </Field>
      <div data-slot="row">
        <DialogClose data-variant="solid">Done</DialogClose>
      </div>
      <DialogClose aria-label="Close">
        <XIcon aria-hidden="true" />
      </DialogClose>
    </DialogContent>
  </Dialog>
</template>
Open Share, then close it with either Close button, Escape, or a press outside. Focus returns to Share.

Installation

npm install @ui-sdk/vue @ui-sdk/core

Composition

Use the following composition to build a Dialog:

Dialog
├── DialogTrigger
├── DialogBackdrop
└── DialogContent
    ├── DialogTitle
    ├── DialogDescription
    └── DialogClose

The title names the dialog; the description gives it context. A dialog can have several Close parts. Give an icon-only close button an accessible name, as the first example does.

The backdrop is optional. Without one, style the content’s ::backdrop. For a question that requires an explicit answer, use Alert Dialog.

Usage

Import the parts and put them together:

<script setup lang="ts">
import {
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
</script>

<template>
  <Dialog>
    <DialogTrigger>Open</DialogTrigger>
    <DialogBackdrop />
    <DialogContent>
      <DialogTitle>Project details</DialogTitle>
      <DialogDescription
        >Review the details before continuing.</DialogDescription
      >
      <DialogClose>Close</DialogClose>
    </DialogContent>
  </Dialog>
</template>

Build Your Own

@ui-sdk/vue/dialog comes with a ready-made Dialog. If you'd like to build your own, with your own names, start from the dialog primitive in @ui-sdk/core:

share.ts
import { dialog } from "@ui-sdk/core/dialog"
import { createParts } from "@ui-sdk/vue/primitive"

const {
  Root: Share,
  Trigger: ShareTrigger,
  Backdrop: ShareBackdrop,
  Content: SharePanel,
  Title: ShareTitle,
  Description: ShareDescription,
  Close: ShareClose,
} = createParts(dialog, {
  trigger: "button",
  backdrop: "div",
  content: "div",
  title: "h2",
  description: "p",
  close: "button",
})

export {
  Share,
  ShareBackdrop,
  ShareClose,
  ShareDescription,
  SharePanel,
  ShareTitle,
  ShareTrigger,
}
<template>
  <Share>
    <ShareTrigger>Share</ShareTrigger>
    <ShareBackdrop />
    <SharePanel>
      <ShareTitle>Share this page</ShareTitle>
      <ShareDescription>Anyone with the link can view it.</ShareDescription>
      <ShareClose>Done</ShareClose>
    </SharePanel>
  </Share>
</template>

Each part keeps the behavior, state and data attributes of its ready-made counterpart: the content opens in the top layer, traps focus and makes the page inert. See Rendering and Custom Parts for more.

Scrollable Content

Keep the header and actions outside the scrolling area. A viewport height limit, a shrinking middle grid row, and overflow-y: auto keep long content usable. initial-focus="content" focuses the dialog itself so reading starts at the top.

<script setup lang="ts">
import {
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"

const paragraphs = [
  "These terms govern your use of the service. By creating an account, you agree to them and to the privacy policy that explains how we handle your data.",
  "You're responsible for the content you upload and for keeping your password safe. Tell us right away if you think someone else has used your account.",
  "We may change the service, and these terms, as the product grows. When a change affects you, we'll let you know by email at least 30 days before it takes effect.",
  "You can stop using the service at any time. We'll keep your data for 30 days after you close your account, so you can export it, and then delete it.",
  "The service is provided as is. To the extent the law allows, we aren't liable for indirect damages, lost profits or lost data.",
  "If you have questions about these terms, write to us. We read every message and reply within two working days.",
]
</script>

<template>
  <Dialog>
    <DialogTrigger>Scrollable Content</DialogTrigger>
    <DialogBackdrop />
    <DialogContent initial-focus="content">
      <div data-slot="stack">
        <DialogTitle>Terms of service</DialogTitle>
        <DialogDescription>Please read before you continue.</DialogDescription>
      </div>
      <div data-slot="scroll">
        <p v-for="paragraph in paragraphs" :key="paragraph">
          {{ paragraph }}
        </p>
      </div>
      <div data-slot="row">
        <DialogClose>Decline</DialogClose>
        <DialogClose data-variant="solid" value="accept">Accept</DialogClose>
      </div>
    </DialogContent>
  </Dialog>
</template>
Open Scrollable Content in a short window. Scroll the terms while the title and Decline/Accept buttons stay in view.

Forms

A form with method="dialog" closes the dialog on a valid submission. The submit button’s value becomes the returnValue, just like a Close part’s value. An ordinary form stays open until you close the dialog yourself.

Console
<script setup lang="ts">
import {
  Dialog,
  DialogBackdrop,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
import { useLog } from "./log"

const log = useLog()

function onOpenChange(
  open: boolean,
  details: { reason: string; returnValue?: string }
) {
  if (!open) {
    log(
      details.returnValue
        ? `Saved as ${details.returnValue}`
        : `Closed (${details.reason})`
    )
  }
}
</script>

<template>
  <Dialog @open-change="onOpenChange">
    <DialogTrigger>New Article</DialogTrigger>
    <DialogBackdrop />
    <DialogContent>
      <div data-slot="stack">
        <DialogTitle>New article</DialogTitle>
        <DialogDescription
          >Save it as a draft or publish it now.</DialogDescription
        >
      </div>
      <form data-slot="stack" method="dialog">
        <Field>
          <FieldLabel>Title</FieldLabel>
          <Input required defaultValue="Shipping updates for spring" />
        </Field>
        <div data-slot="row">
          <button type="submit" value="draft">Save Draft</button>
          <button data-variant="solid" type="submit" value="published">
            Publish
          </button>
        </div>
      </form>
    </DialogContent>
  </Dialog>
</template>
Open New Article and choose Save Draft or Publish. The console logs the submitted button's value. An empty title prevents submission.

Focus

Use initial-focus to pick where focus starts, and final-focus to choose where it goes after closing. Each takes a selector, an element or a function returning one. The default returns to the trigger, or to the element focused before a controller opened the dialog. See popup focus for the shared focus rules.

<DialogContent initial-focus="#invite-email" :final-focus="() => nextStep" />

Controlled

Use v-model:open to keep the dialog's state in your component. Cancel a proposed change with details.cancel() in @open-change. @open-change-complete reports when opening or closing has finished; see state and events for the common change contract.

Console
<script setup lang="ts">
import { CheckIcon } from "@lucide/vue"
import { Checkbox, CheckboxIndicator } from "@ui-sdk/vue/checkbox"
import {
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
import { ref } from "vue"
import { useLog } from "./log"

const topics = [
  { label: "Product updates", checked: true },
  { label: "Security alerts", checked: true },
  { label: "Weekly digest", checked: false },
]

const log = useLog()
const open = ref(false)

function onOpenChange(next: boolean, details: { reason: string }) {
  log(`${next ? "Opened" : "Closed"} (${details.reason})`)
}
</script>

<template>
  <div data-slot="stack">
    <div data-slot="controls">
      <label data-slot="label">
        <Checkbox
          :checked="open"
          @checked-change="(next) => (open = next === true)"
        >
          <CheckboxIndicator>
            <CheckIcon aria-hidden="true" />
          </CheckboxIndicator>
        </Checkbox>
        Open
      </label>
    </div>
    <Dialog
      v-model:open="open"
      @open-change="onOpenChange"
      @open-change-complete="
        (next: boolean) => log(next ? 'Finished opening' : 'Finished closing')
      "
    >
      <DialogTrigger>Notification Settings</DialogTrigger>
      <DialogBackdrop />
      <DialogContent>
        <div data-slot="stack">
          <DialogTitle>Notification settings</DialogTitle>
          <DialogDescription>Choose what we email you about.</DialogDescription>
        </div>
        <div data-slot="stack">
          <label v-for="topic in topics" :key="topic.label" data-slot="label">
            <Checkbox :default-checked="topic.checked">
              <CheckboxIndicator>
                <CheckIcon aria-hidden="true" />
              </CheckboxIndicator>
            </Checkbox>
            {{ topic.label }}
          </label>
        </div>
        <div data-slot="row">
          <DialogClose data-variant="solid">Done</DialogClose>
        </div>
      </DialogContent>
    </Dialog>
  </div>
</template>
Check Open or press Notification Settings, then close the dialog. The console logs each change, its reason and when it finishes.

Keyboard Shortcut

A trigger’s shortcut opens it from the keyboard. mod+j means Command+J on Apple platforms and Control+J elsewhere. The Shortcut part displays the right keys and the trigger exposes aria-keyshortcuts.

<script setup lang="ts">
import {
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogShortcut,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
import { PlusIcon } from "@lucide/vue"
</script>

<template>
  <Dialog>
    <DialogTrigger shortcut="mod+j">
      <PlusIcon aria-hidden="true" />
      New Contact
      <DialogShortcut />
    </DialogTrigger>
    <DialogBackdrop />
    <DialogContent>
      <div data-slot="stack">
        <DialogTitle>New contact</DialogTitle>
        <DialogDescription>Add someone to your address book.</DialogDescription>
      </div>
      <form data-slot="stack" method="dialog">
        <Field>
          <FieldLabel>Name</FieldLabel>
          <Input name="name" required placeholder="Kofi Mensah" />
        </Field>
        <Field>
          <FieldLabel>Email</FieldLabel>
          <Input
            name="email"
            type="email"
            required
            placeholder="kofi@example.com"
          />
        </Field>
        <div data-slot="row">
          <DialogClose>Cancel</DialogClose>
          <button data-variant="solid" type="submit" value="save">
            Save Contact
          </button>
        </div>
      </form>
    </DialogContent>
  </Dialog>
</template>
Press Command+J or Control+J to open New contact. The button shows the keys, and Escape returns focus to it.

Animation

The content and backdrop have data-starting-style while they open and data-ending-style while they close. Transition from those states, and the dialog stays mounted until the exit finishes. @open-change-complete runs after the transition, and keep-mounted keeps the content in the page while closed.

[data-slot="dialog-content"] {
  transition:
    opacity 0.2s,
    translate 0.25s cubic-bezier(0.22, 1, 0.36, 1),
    scale 0.25s cubic-bezier(0.22, 1, 0.36, 1);

  &:is([data-starting-style], [data-ending-style]) {
    opacity: 0;
    translate: 0 16px;
    scale: 0.96;
  }

  &[data-ending-style] {
    transition-duration: 0.15s;
  }
}
Console
<script setup lang="ts">
import {
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
import { useLog } from "./log"

const log = useLog()
</script>

<template>
  <Dialog
    @open-change-complete="
      (open: boolean) => log(open ? 'Finished opening' : 'Finished closing')
    "
  >
    <DialogTrigger>Slide In</DialogTrigger>
    <DialogBackdrop />
    <DialogContent keep-mounted>
      <div data-slot="stack">
        <DialogTitle>Slide and fade</DialogTitle>
        <DialogDescription
          >300ms in and out. Focus returns as soon as it starts
          closing.</DialogDescription
        >
      </div>
      <div data-slot="row">
        <DialogClose data-variant="solid">Close</DialogClose>
      </div>
    </DialogContent>
  </Dialog>
</template>
Open the dialog and close it. The console logs when each animation finishes; focus returns as closing starts.

modal controls how the dialog shares the page:

  • true, the default, makes the page inert, locks scrolling, and keeps Tab inside.
  • "trap-focus" keeps Tab inside while the page can still scroll and receive clicks. A click on the page also closes the dialog, unless close-on-outside-press is false.
  • false puts the dialog beside the page and lets focus leave it. Escape closes it while focus is inside; outside presses close it only when close-on-outside-press is enabled.

To keep a small part of the page usable while a modal dialog is open, like a chat launcher, pass it to persistent-elements: an array of elements or selectors, or a function returning elements when the dialog opens. Persistent elements don't change stacking on their own.

Dialogs render where you put them and use the browser's top layer. Set container when their DOM needs to live elsewhere, like a shadow root. The popup guide covers containers and iframes.

<script setup lang="ts">
import { CheckIcon, ChevronDownIcon } from "@lucide/vue"
import { Checkbox, CheckboxIndicator } from "@ui-sdk/vue/checkbox"
import {
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
import {
  Select,
  SelectContent,
  SelectItem,
  SelectItemIndicator,
  SelectLabel,
  SelectTrigger,
  SelectValue,
} from "@ui-sdk/vue/select"
import { computed, ref } from "vue"

const modes = [
  { value: "true", label: "Modal" },
  { value: "trap-focus", label: "Trap focus" },
  { value: "false", label: "Non-modal" },
]

type Mode = "true" | "trap-focus" | "false"

const notes = {
  true: "The rest of the page is inert and doesn't scroll.",
  "trap-focus":
    "Tab stays inside, and the page still scrolls and takes clicks.",
  false:
    "The page stays usable. Tab leaves the notes, and Escape closes them while focus is inside.",
}

const mode = ref<Mode>("false")
const outside = ref(false)
const modal = computed(() =>
  mode.value === "true" ? true : mode.value === "false" ? false : "trap-focus"
)
</script>

<template>
  <div data-slot="stack">
    <div data-slot="controls">
      <Select
        :items="modes"
        :value="mode"
        @value-change="(next) => next && (mode = next as Mode)"
      >
        <SelectLabel>Modal</SelectLabel>
        <SelectTrigger>
          <SelectValue />
          <ChevronDownIcon />
        </SelectTrigger>
        <SelectContent>
          <SelectItem
            v-for="option in modes"
            :key="option.value"
            :value="option.value"
          >
            {{ option.label }}
            <SelectItemIndicator>
              <CheckIcon />
            </SelectItemIndicator>
          </SelectItem>
        </SelectContent>
      </Select>
      <label data-slot="label">
        <Checkbox
          :checked="outside"
          @checked-change="(next) => (outside = next === true)"
        >
          <CheckboxIndicator>
            <CheckIcon aria-hidden="true" />
          </CheckboxIndicator>
        </Checkbox>
        Close on outside press
      </label>
    </div>
    <Dialog :modal="modal" :close-on-outside-press="outside">
      <DialogTrigger>Open Notes</DialogTrigger>
      <DialogBackdrop v-if="modal === true" />
      <DialogContent>
        <div data-slot="stack">
          <DialogTitle>Notes</DialogTitle>
          <DialogDescription>{{ notes[mode] }}</DialogDescription>
        </div>
        <textarea aria-label="Notes">
Call the printer about the proofs.</textarea>
        <div data-slot="row">
          <DialogClose data-variant="solid">Done</DialogClose>
        </div>
      </DialogContent>
    </Dialog>
  </div>
</template>
Choose a mode, open Notes, and try Tab or clicking the page. Check Close on outside press to compare dismissal.

Warn Before Closing a Dirty Form

Set dismissible to false while there are unsaved changes. Escape, an outside press, or a back gesture then keeps the dialog open and emits @dismiss-attempt. Explicit Close parts and controller calls still work, so you can offer a deliberate way out.

<script setup lang="ts">
import {
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import { ref } from "vue"

const open = ref(false)
const dirty = ref(false)
const asking = ref(false)
let post: HTMLTextAreaElement | undefined

function onInput(event: Event) {
  post = event.target as HTMLTextAreaElement
  dirty.value = post.value !== ""
}

function close() {
  open.value = false
  dirty.value = false
  asking.value = false
}

function keepEditing() {
  asking.value = false
  post?.focus()
}
</script>

<template>
  <Dialog
    :open="open"
    :dismissible="!dirty"
    @update:open="(next: boolean) => (next ? (open = true) : close())"
    @dismiss-attempt="asking = true"
  >
    <DialogTrigger>Write a Post</DialogTrigger>
    <DialogBackdrop />
    <DialogContent>
      <div data-slot="stack">
        <DialogTitle>New post</DialogTitle>
        <DialogDescription>Share an update with your team.</DialogDescription>
      </div>
      <Field>
        <FieldLabel>Post</FieldLabel>
        <FieldControl @input="onInput">
          <template #render="{ props }">
            <textarea v-bind="props" placeholder="What's new?" />
          </template>
        </FieldControl>
      </Field>
      <div v-if="asking" data-slot="row" role="alert">
        Discard your changes?
        <div data-slot="row">
          <button type="button" @click="keepEditing">Keep Editing</button>
          <button data-variant="solid" type="button" @click="close">
            Discard
          </button>
        </div>
      </div>
      <div v-else data-slot="row">
        <DialogClose data-variant="solid" value="post">Post</DialogClose>
      </div>
    </DialogContent>
  </Dialog>
</template>
Type a post, then press Escape or click outside. Keep editing returns to the field; Discard closes the dialog and clears the draft.

Nested Dialogs

A dialog opened inside another joins its stack. Escape closes the topmost dialog and returns focus to its trigger. Closing the parent also closes its children. data-nested-open and --dialog-stack let you show which layer is active.

<script setup lang="ts">
import {
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
</script>

<template>
  <Dialog>
    <DialogTrigger>Account</DialogTrigger>
    <DialogBackdrop />
    <DialogContent>
      <div data-slot="stack">
        <DialogTitle>Account</DialogTitle>
        <DialogDescription>Manage how you sign in.</DialogDescription>
      </div>
      <div data-slot="card">
        <div data-slot="stack">
          <span>Password</span>
          <span data-slot="hint">Last changed 3 months ago</span>
        </div>
        <Dialog>
          <DialogTrigger>Change Password</DialogTrigger>
          <DialogBackdrop />
          <DialogContent>
            <div data-slot="stack">
              <DialogTitle>Change password</DialogTitle>
              <DialogDescription>Use at least 12 characters.</DialogDescription>
            </div>
            <Field>
              <FieldLabel>New password</FieldLabel>
              <Input type="password" />
            </Field>
            <div data-slot="row">
              <DialogClose>Cancel</DialogClose>
              <DialogClose data-variant="solid">Update</DialogClose>
            </div>
          </DialogContent>
        </Dialog>
      </div>
      <div data-slot="row">
        <DialogClose data-variant="solid">Done</DialogClose>
      </div>
    </DialogContent>
  </Dialog>
</template>
Open Account, then Change Password. Press Escape once to return to Account, and again to close it.

Opening from a Menu Item

Render the dialog outside the menu and open it with the dialog’s controller. When the item disappears, the menu’s trigger becomes the place to return focus.

<script setup lang="ts">
import {
  createDialogController,
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
} from "@ui-sdk/vue/dialog"
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
import { Menu, MenuContent, MenuItem, MenuTrigger } from "@ui-sdk/vue/menu"
import { CopyIcon, EllipsisIcon, PencilIcon } from "@lucide/vue"

const rename = createDialogController()
</script>

<template>
  <Menu>
    <MenuTrigger aria-label="File actions">
      <EllipsisIcon aria-hidden="true" />
    </MenuTrigger>
    <MenuContent>
      <MenuItem @select="rename.open()">
        <PencilIcon aria-hidden="true" />
        Rename…
      </MenuItem>
      <MenuItem>
        <CopyIcon aria-hidden="true" />
        Duplicate
      </MenuItem>
    </MenuContent>
  </Menu>
  <Dialog :controller="rename">
    <DialogBackdrop />
    <DialogContent>
      <div data-slot="stack">
        <DialogTitle>Rename file</DialogTitle>
        <DialogDescription>Names must be unique in a folder.</DialogDescription>
      </div>
      <Field>
        <FieldLabel>Name</FieldLabel>
        <Input defaultValue="report.pdf" />
      </Field>
      <div data-slot="row">
        <DialogClose>Cancel</DialogClose>
        <DialogClose data-variant="solid" value="rename">Rename</DialogClose>
      </div>
    </DialogContent>
  </Dialog>
</template>
Open File Actions and choose Rename. Close the dialog to return focus to the File Actions button.

Opening from Anywhere

Connect several triggers to one createDialogController<Payload, Result>(). Each trigger passes a payload; a typed content alias, such as DialogContent<Invoice>, reads it from state.payload in its default slot. controller.open({ payload }) opens it from code and returns a promise that resolves when it closes, with the reason and any returnValue. Each trigger remains the return-focus target for the dialog it opened. See controllers for the shared controller pattern.

Console
<script setup lang="ts">
import {
  createDialogController,
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
import { useLog } from "./log"

type Invoice = {
  id: string
  customer: string
  amount: string
  status: "Paid" | "Due"
}

const invoices: Invoice[] = [
  { id: "INV-001", customer: "Acme", amount: "$250.00", status: "Paid" },
  { id: "INV-002", customer: "Globex", amount: "$150.00", status: "Due" },
  { id: "INV-003", customer: "Initech", amount: "$350.00", status: "Due" },
]

const reminder = createDialogController<Invoice, "send">()
const InvoiceDialogContent = DialogContent<Invoice>
const log = useLog()

async function remindFromCode() {
  const { reason, returnValue } = await reminder.open({ payload: invoices[2] })
  log(returnValue === "send" ? "Reminder sent from code" : `Closed (${reason})`)
}

function onOpenChange(open: boolean, details: { returnValue?: string }) {
  if (!open && details.returnValue === "send") {
    log("Reminder sent")
  }
}
</script>

<template>
  <div data-slot="stack">
    <div data-slot="controls">
      <button type="button" @click="remindFromCode">Open from Code</button>
    </div>
    <ul data-slot="list">
      <li v-for="invoice in invoices" :key="invoice.id" data-slot="row">
        {{ invoice.customer }}
        <span data-slot="hint"
          >{{ invoice.amount }} · {{ invoice.status }}</span
        >
        <DialogTrigger
          :controller="reminder"
          :payload="invoice"
          :disabled="invoice.status === 'Paid'"
          :aria-label="`Remind ${invoice.customer}`"
        >
          Remind
        </DialogTrigger>
      </li>
    </ul>
    <Dialog :controller="reminder" @open-change="onOpenChange">
      <DialogBackdrop />
      <InvoiceDialogContent v-slot="{ state }">
        <div data-slot="stack">
          <DialogTitle>Remind {{ state.payload?.customer }}</DialogTitle>
          <DialogDescription>
            {{ state.payload?.id }} for {{ state.payload?.amount }} is due.
            We'll email the billing contact.
          </DialogDescription>
        </div>
        <div data-slot="row">
          <DialogClose>Cancel</DialogClose>
          <DialogClose data-variant="solid" value="send"
            >Send reminder</DialogClose
          >
        </div>
      </InvoiceDialogContent>
    </Dialog>
  </div>
</template>
Open a reminder from either unpaid invoice, or press Open from Code. The same dialog shows that invoice, and the console logs how it closed.

Presentation

presentation="sheet" presents the same task as a sheet. Use "auto" to choose a sheet on small touch screens and a centered dialog elsewhere, decided each time it opens. A swipe down closes a dismissible sheet; a protected one springs back and reports a dismissal attempt.

Style data-presentation to support both layouts. The sheet manages its own position and movement, so do not apply the centered dialog’s translation to it. --sheet-backdrop styles the dimmed page when no Backdrop part is present.

<script setup lang="ts">
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
import { Field, FieldLabel } from "@ui-sdk/vue/field"
import { Input } from "@ui-sdk/vue/input"
</script>

<template>
  <Dialog presentation="sheet">
    <DialogTrigger>Edit Profile</DialogTrigger>
    <DialogContent>
      <div data-slot="stack">
        <DialogTitle>Edit profile</DialogTitle>
        <DialogDescription
          >Make changes to your profile here. Save when you're
          done.</DialogDescription
        >
      </div>
      <Field>
        <FieldLabel>Name</FieldLabel>
        <Input defaultValue="Hollis Grant" />
      </Field>
      <Field>
        <FieldLabel>Username</FieldLabel>
        <Input defaultValue="@hollis" />
      </Field>
      <div data-slot="row">
        <DialogClose>Cancel</DialogClose>
        <DialogClose data-variant="solid" value="save"
          >Save Changes</DialogClose
        >
      </div>
    </DialogContent>
  </Dialog>
</template>
Open Edit Profile as a sheet. On a touch screen, drag it down to dismiss it, or use Cancel or Save Changes.

Custom Rendering

Every part takes a render slot, which receives the props to bind and the part's state, and the default slot receives the state too.

<script setup lang="ts">
import {
  Dialog,
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogShortcut,
  DialogTitle,
  DialogTrigger,
} from "@ui-sdk/vue/dialog"
</script>

<template>
  <Dialog>
    <DialogTrigger shortcut="mod+i">
      <template #render="{ props, state }">
        <button v-bind="props">
          {{ state.open ? "Viewing" : "View Details" }}
          <DialogShortcut v-slot="{ state: shortcut }">{{
            shortcut.text
          }}</DialogShortcut>
        </button>
      </template>
    </DialogTrigger>
    <DialogBackdrop />
    <DialogContent v-slot="{ state }">
      <div data-slot="stack">
        <DialogTitle>
          <template #render="{ props }">
            <h3 v-bind="props">Details</h3>
          </template>
        </DialogTitle>
        <DialogDescription>
          {{
            state.nested
              ? "Opened from another dialog."
              : "Quarterly report, updated today."
          }}
        </DialogDescription>
      </div>
      <div data-slot="row">
        <DialogClose>Close</DialogClose>
        <DialogClose data-variant="solid" href="https://example.com/details">
          <template #render="{ props }">
            <a v-bind="props">Open the Full Page</a>
          </template>
        </DialogClose>
      </div>
    </DialogContent>
  </Dialog>
</template>
Open View Details. The trigger's label and the description come from their state, and Close renders as a link.

Styling

Each part has a data-slot, such as dialog-content, and shows its state through the attributes listed under Data Attributes. Use data-open and data-closed for each state, and data-starting-style and data-ending-style for transitions.

DialogContent

VariableWhat it holds
--dialog-stackHow many dialogs are open above this one, nested inside it. 0 for the topmost.
--keyboard-insetUnless it presents as a sheet: how many pixels of the page the on-screen keyboard covers, 0 without one.
--visual-viewport-widthUnless it presents as a sheet: the width of the part of the page you can see.
--visual-viewport-heightUnless it presents as a sheet: the height of the part of the page you can see, above the keyboard.
--visual-viewport-topUnless it presents as a sheet: how far the part of the page you can see is scrolled from the top of the layout, as when the keyboard pushes it up.
--drawer-progressWhile it presents as a sheet: how far open the sheet is, from 0 closed to 1 at its largest snap point. Never past 1.
--drawer-dimWhile it presents as a sheet: how dim the page behind is, from 0 to 1. The backdrop's opacity follows it.
--drawer-expandWhile it presents as a sheet: 0 at the second-largest snap point and below, 1 at the largest. With one snap point, the whole travel.
--drawer-stackWhile it presents as a sheet: how many sheets opened from inside this one are open above it, rising smoothly as each one opens. Push it back with it.
--sheet-backdropSet it yourself: the color the page dims to while it presents as a sheet. Black at 0.2 by default.

Viewport

VariableWhat it holds
--keyboard-insetWhile it presents as a sheet: how many pixels of the page the on-screen keyboard covers, 0 without one.
--visual-viewport-widthWhile it presents as a sheet: the width of the part of the page you can see.
--visual-viewport-heightWhile it presents as a sheet: the height of the part of the page you can see, above the keyboard.
--visual-viewport-topWhile it presents as a sheet: how far the part of the page you can see is scrolled from the top of the layout, as when the keyboard pushes it up.

Data Attributes

DialogTrigger

[data-slot="dialog-trigger"]

AttributeWhat it means
data-closedPresent while the dialog is closed, including while it animates out.
data-disabledPresent when the trigger is disabled.
data-openPresent while the dialog is open. On a trigger, while it's open from that trigger.

DialogBackdrop

[data-slot="dialog-backdrop"]

AttributeWhat it means
data-closedPresent while the dialog is closed, including while it animates out.
data-openPresent while the dialog is open. On a trigger, while it's open from that trigger.
data-starting-stylePresent for the first frame. Style the state you animate from.
data-ending-stylePresent while the dialog animates out. Style the state you animate to.

DialogContent

[data-slot="dialog-content"]

AttributeWhat it means
data-closedPresent while the dialog is closed, including while it animates out.
data-presentationdialogsheetHow the dialog presents this time it's open.
data-openPresent while the dialog is open. On a trigger, while it's open from that trigger.
data-starting-stylePresent for the first frame. Style the state you animate from.
data-ending-stylePresent while the dialog animates out. Style the state you animate to.
data-keyboardPresent while the on-screen keyboard covers part of the page.

DialogClose

[data-slot="dialog-close"]

AttributeWhat it means
data-pendingPresent on a Close part while its action runs.

API Reference

Props are the same as below, and callbacks are events.

Dialog

container?DocumentFragment | Element | null
Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
open?boolean
Whether the dialog is open. Pass it to control the dialog.
defaultOpen?boolean
Whether the dialog starts open, when uncontrolled. Focus moves into it once it's on the page.
@open-change-complete((open: boolean) => void)
Runs once the dialog has finished opening or closing, after any animation.
dismissible?boolean
Whether Escape, an outside press and Android's back gesture can close the dialog. Close parts, triggers and the controller always can. Pass false while a form has unsaved changes, and ask in @dismiss-attempt.
@dismiss-attempt((details: DialogDismissAttemptDetails) => void)
Runs when a dismissal was refused, because dismissible is false, an outside press doesn't close it, or a Close part's action is running. Ask "Discard changes?" here.
persistentElements?(string | Element)[] | (() => Element[])
Elements that stay usable while the dialog makes the page inert, like a chat launcher or a password manager's button. Elements, CSS selectors, or a function that returns elements, read when the dialog opens. Presses on them never close it.
pendingAnnouncement?string
What screen readers hear once a Close part's action has been running for a second, so a slow action doesn't pass in silence. Set it in the page's language. An empty string says nothing.
debug?boolean
Logs every state change with its reason to the console, in development builds.
@open-change((open: boolean, details: DialogOpenChangeDetails) => void)
Runs when the dialog wants to open or close. details.reason says why, details.cancel() stops it, and details.returnValue carries what closed it.
@payload-change((payload: unknown, details: ChangeDetails<DialogPayloadChangeReason>) => void)
Runs when the payload the content shows changes: a trigger with another payload opens the dialog, or takes a non-modal dialog over while it's open, which fires no @open-change, and so does a controller's open({ payload }) on the open dialog. details.cancel() keeps the previous payload.
modal?"trap-focus" | boolean
true: the rest of the page is inert and doesn't scroll, focus is trapped, and an outside press only closes the dialog. "trap-focus": traps focus, and leaves the page scrollable and clickable. false: a dialog beside the page, which Tab can leave and outside presses don't close.
closeOnOutsidePress?boolean
Whether pressing outside the dialog, like on its backdrop, closes it. The press counts once it's released outside too, so dragging a text selection out of a field doesn't close it.
presentation?PresentationSetting<"dialog">
How the dialog presents. "sheet" slides it up from the bottom of the screen, where it can be swiped away, and "auto" does that on small touch screens. Decided each time it opens; the server renders "dialog" for "auto".
controller?PopupController<any, DialogOpenChangeReason, {}, any, DialogPayloadChangeReason>
Opens, closes and inspects the dialog from anywhere, and connects triggers outside it. Create one with createDialogController().

DialogTrigger

A trigger outside the dialog also takes controller.

disabled?boolean
Stops the trigger from opening the dialog. A native button can't be focused or pressed, unless focusableWhenDisabled is set.
focusableWhenDisabled?boolean
Keeps a disabled trigger in the tab order with aria-disabled instead of the native attribute, so it can host a tooltip that says why. Presses still do nothing.
payload?unknown
Data for the content to render when this trigger opens the dialog, like the row it belongs to.
shortcut?string
A keyboard shortcut that presses the trigger, like "mod+k". mod is Command on Apple platforms and Control elsewhere. Sets aria-keyshortcuts, and a Shortcut part inside shows it. A modal dialog pauses the page's shortcuts while it's open.
controller?PopupController<any, DialogOpenChangeReason, {}, any, DialogPayloadChangeReason>
Connects a trigger outside the dialog, like one per table row, to the dialog with this controller.

DialogBackdrop

Dims the page behind a modal dialog. Renders a div.

DialogContent

container?DocumentFragment | Element | null
Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
initialFocus?DialogInitialFocus
Where focus goes when the dialog opens. Opening with touch focuses the dialog itself, so no on-screen keyboard appears.
finalFocus?PopupFocusTarget
Where focus goes when the dialog closes while focus is inside it.
keepMounted?boolean
Whether the dialog stays in the page, hidden, while closed. For animation libraries that drive the exit from state.

DialogTitle

Names the dialog. Renders an h2.

DialogDescription

Describes the dialog while it's rendered. Renders a p.

DialogClose

Its @action handler receives the event and { source }, how the part was pressed, as Button describes.

value?string
Reported as returnValue in @open-change and by the controller's open(). createConfirm() resolves true for "confirm".
action?((event: Event | undefined, details: ActionDetails) => unknown)
Runs when the part is pressed, before the dialog closes. A returned Promise keeps the dialog open while it runs: the part gets data-pending, aria-busy and aria-disabled, screen readers hear the dialog's pendingAnnouncement after a second, and nothing but the controller closes the dialog. It closes with reason "action" once the Promise resolves. A rejection keeps it open and puts the reason in the part's error state until the next press, or until the dialog opens again. details.source says how the part was pressed, for changes made after an await.

DialogShortcut

shortcut?string
The keys to show. Inside a trigger, its shortcut.

State

What render functions, state-based class names and slots receive, per part.

DialogTrigger:

openboolean
Whether the dialog is open from this trigger.
disabledboolean
Set by the trigger's disabled prop, which stops it opening the dialog.

DialogBackdrop:

openboolean
Whether the dialog is open. False while it animates out.
nestedboolean
Whether the dialog was opened from inside another dialog.
nestedOpenboolean
Whether a dialog opened from inside this one is open.

DialogContent:

openboolean
Whether the dialog is open. False while it animates out.
modalboolean | "trap-focus"
The modal setting. Always true for an alert dialog.
nestedboolean
Whether the dialog was opened from inside another dialog.
nestedOpenboolean
Whether a dialog opened from inside this one is open.
stacknumber
How many dialogs are open above this one, nested inside it.
payloadPayload | undefined
The payload of the last open, from the trigger that opened it or a controller, typed as the controller's Payload.
pendingboolean
Whether a Close part's action is running.
presentation"dialog" | "sheet"
How it presents this time it's open.

DialogClose:

pendingboolean
Whether this part's action is running.
errorunknown
Why this part's last action failed, until it's pressed again or the dialog opens again.

DialogShortcut:

textstring
The shortcut formatted for this platform: ⌘K on Apple platforms and Ctrl+K elsewhere. Empty without one.

Reasons

details.reason says why the dialog opened or closed.

trigger-pressMouseEvent | KeyboardEvent | TouchEvent
Click, tap, Enter or Space on the part that opens, closes or toggles. Arrow keys that open a menu or submenu count too. A tap on a combobox's input that opens a sheet reports its touchend.
close-pressMouseEvent | KeyboardEvent | SubmitEvent
A Close part was pressed, or a form with method="dialog" was submitted.
outside-pressMouseEvent
A press outside the layer.
escape-keyKeyboardEvent
Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
parent-closenone
The parent layer closed.
backEvent
Going back: the Android back button or gesture, or Backspace in an empty command input, which returns to the previous page.
actionMouseEvent | KeyboardEvent
A Close part's action finished.
shortcutKeyboardEvent
A keyboard shortcut, like a trigger's shortcut.
swipePointerEvent | TouchEvent
A swipe gesture: a finger, mouse or pen dragged it.
imperativenone
A controller or api call, or a property set on a web component.

For a payload change, it says what opened the dialog or took it over.

trigger-pressMouseEvent | KeyboardEvent | TouchEvent
Click, tap, Enter or Space on the part that opens, closes or toggles. Arrow keys that open a menu or submenu count too. A tap on a combobox's input that opens a sheet reports its touchend.
shortcutKeyboardEvent
A keyboard shortcut, like a trigger's shortcut.
imperativenone
A controller or api call, or a property set on a web component.

The dismissals dismissible can refuse:

outside-pressMouseEvent
A press outside the layer.
escape-keyKeyboardEvent
Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
backEvent
Going back: the Android back button or gesture, or Backspace in an empty command input, which returns to the previous page.
swipePointerEvent | TouchEvent
A swipe gesture: a finger, mouse or pen dragged it.

Controller

Create one with createDialogController<Payload, Result>() and pass it as controller, to the dialog and to any triggers outside it.

Every write method takes an optional { reason, event }, passed to @open-change. Closing with a controller always works, even when the dialog isn't dismissible or an action is running.

isOpen()() => boolean
Whether it's open. False as soon as it starts closing, while it still animates out.
setOpen(open, options?)(open: boolean, options?: PopupChangeOptions<DialogOpenChangeReason> | undefined) => boolean
Opens or closes it. Returns false when the change was canceled or it was already open or closed.
open(options?)(options?: (PopupChangeOptions<DialogPayloadChangeReason> & { payload?: Payload | undefined; anchor?: Anchor | undefined; signal?: AbortSignal | undefined; }) | undefined) => Promise<...>
Opens it, and resolves once it closes, with why, how and any return value. Resolves exactly once and never rejects: on the next close from any source, when signal aborts, or with reason "unmount" when the component leaves the page.
close(options?)(options?: (PopupChangeOptions<DialogOpenChangeReason> & { returnValue?: Result | undefined; }) | undefined) => boolean
Closes it. returnValue is passed to the promise open() returned. Returns false when the close was canceled or it was already closed.
toggle(options?)(options?: PopupChangeOptions<DialogOpenChangeReason> | undefined) => boolean
Opens it when it's closed, and closes it when it's open. Returns false when the change was canceled.
getPayload()() => Payload | undefined
The payload of the last open, from a controller or the trigger that opened it.
focus()() => void
Moves focus to the trigger that opened it last, or the first trigger.

Events

Events get the new state first, then the details. v-model only updates when @open-change wasn't canceled.

BindingOnReceives
v-model:openDialogWhether the dialog is open
@open-changeDialog(open, details): the new state, the reason and any returnValue
@open-change-completeDialog(open), after the animation
@payload-changeDialog(payload, details): the content's new payload, and the reason
@dismiss-attemptDialog({ reason, event }), when a dismissal was refused

Accessibility

The trigger is a button that opens a dialog, and the dialog follows the WAI-ARIA modal dialog pattern: aria-modal while it's modal, labelled by its title, described by its description only while one is rendered. Every line below is an automated test.

Keyboard

KeyDoes
Enter, SpaceOn the trigger, opens the dialog
Tab, Shift+TabMoves through the dialog's controls, staying inside while it's modal
EscapeCloses the topmost dialog and returns focus to its trigger
A trigger's shortcutOpens its dialog from anywhere on the page

Tested Behavior

Trigger
  • Advertises a dialog.
  • Click opens the dialog.
  • Enter opens the dialog.
  • Space opens the dialog.
Focus
  • Opening moves focus to the first focusable element.
  • Each time focus moves in, the dialog is named by its title and described by its description.
  • Tab moves through the dialog in order.
  • Tab from the last element wraps to the first.
  • Shift+Tab from the first element wraps to the last.
  • Shift+Tab from the first element wraps to the checked radio of a group outside a form.
  • Tab reaches radios whose group's checked radio is behind the dialog.
  • Tab visits a positive tabindex first, like the browser.
  • A positive tabindex keeps Tab inside a dialog that leaves the page usable.
  • A positive tabindex slotted into a custom element keeps its host's place.
  • With a positive tabindex in the dialog, Tab still moves through a shadow root and slots.
  • With a positive tabindex in the dialog, Tab from a focused element outside the tab order goes to the next stop.
  • Tab from a custom element with a positive tabindex enters its shadow root.
  • Opening focuses the first field even when a later one has a positive tabindex.
  • Escape closes the dialog and returns focus to the trigger.
  • Escape after a click returns focus to the trigger.
  • The close button closes the dialog and returns focus to the trigger.
  • A virtual click from a screen reader moves focus into the dialog.
  • A touch press focuses the dialog itself, so no on-screen keyboard appears.
  • Pressing a button inside keeps the dialog open.
Dismissal
  • Pressing the backdrop closes the dialog.
  • Pressing the backdrop returns focus to the trigger.
  • Clicking inside the dialog keeps it open.
  • An outside press doesn't reach the page.
Presses
  • Selecting text in a field and releasing over the backdrop keeps the dialog open.
  • Pressing the backdrop and releasing inside the dialog keeps it open.
  • A right click on the backdrop keeps the dialog open.
  • A dialog styled only with ::backdrop closes when the backdrop is pressed.
  • With closeOnOutsidePress false, pressing the backdrop keeps the dialog open.
  • Pressing a nested dialog's backdrop closes only the nested dialog.
  • While the dialog animates out, a press on its backdrop doesn't reach the page.
  • Escape right after opening a nested dialog closes only the nested one.
Modal
  • Tab never leaves the dialog.
  • The page doesn't scroll while the dialog is open.
  • The rest of the page is hidden from assistive technology.
  • With modal false, the page stays usable.
Nested dialogs
  • Escape closes only the nested dialog and returns focus to its trigger.
  • The nested dialog's close button closes only it.
  • The outer dialog's open change hears only the outer dialog.
  • Tab stays inside the nested dialog.
  • A second Escape closes the outer dialog.

Runs in React, Vue and web components.

Additional behaviors:

Escape that closes exactly one thing
  • Escape while an input method is composing text keeps the dialog open.
  • Escape closes a non-modal dialog only while focus is inside it.
Focus that always lands somewhere useful
  • Closing returns focus to the trigger before the exit animation finishes.
  • Closing after the trigger is gone moves focus to the element after where it was.
  • Closing after the trigger is gone skips past a later positive tabindex.
  • A dialog open from the start moves focus inside.
  • With initial focus on the content, the dialog itself takes focus.
The outside is inert, except what must stay live
  • The page outside is inert while open and restored exactly after.
  • A live region outside the dialog keeps announcing while it's open.
Non-modal dialogs that behave like the APG
  • Tab leaves a non-modal dialog and the dialog stays open.
  • A non-modal dialog stays open when the page is clicked.
Nested and stacked
  • A dialog opened inside a dialog marks both, for styling.
  • Closing the parent closes the nested dialog with reason parent-close.
Opening from anywhere
  • A controller opens the dialog, moves focus in, and resolves with how it closed.
  • Aborting the signal closes the dialog, and the promise resolves once.
  • A pending open() resolves with reason unmount when the dialog leaves the page. Web components only.
  • A form with method dialog closes the dialog and reports the submitter's value.
  • A confirm helper resolves true for the action and false otherwise.
  • Closing reports why, for every way a dialog closes.
Shortcuts
  • A trigger connected through a controller shows its shortcut in a Shortcut part, and binds it.
Web components
  • The open property and attribute open and close the dialog. Web components only.

Runs in React, Vue and web components.

Opening a dialog from a menu item
  • Choosing the item closes the menu and moves focus into the dialog.
  • Choosing the item with the keyboard moves focus into the dialog.
The page and focus around a dialog opened from a menu item
  • The page around the dialog is inert, the menu's trigger included.
  • Closing the dialog returns focus to the menu's trigger.
  • A dialog the item opens through its open prop returns focus to the menu's trigger. React and Vue only.
Shortcuts
  • A trigger's shortcut opens the dialog.
  • The trigger advertises its shortcut, and shows it to sighted users only.
  • A modal dialog pauses the page's shortcuts and keeps its own.
  • A dialog's own shortcut doesn't run while the dialog is closed.
  • Menu and popover triggers take shortcuts too.
  • Plain keys typed in a text field are text, and modifier shortcuts still run.
  • A plain-key shortcut runs outside text fields.
A dirty form
  • Refuses Escape and outside presses, and reports each attempt.
  • A clean form closes on Escape.
Persistent elements
  • Stay usable while a modal dialog is open, and pressing them keeps it open.
Async actions
  • Keep the alert dialog open and pending, then close with reason action.
  • A failed action keeps the alert dialog open and stops pending.
Popups inside a portaled popover
  • A menu and a dialog inside it render into the popover's container.
Android's back gesture
  • Closes the topmost dialog with reason back.

Runs in React, Vue and web components.

Screen readers hear the same thing in each tested framework, recorded by a virtual screen reader:

  • Announcements while using the dialog with a keyboard.
  • Announcements while using the alert dialog with a keyboard.

Runs in React, Vue and web components.