Dialog
updatedWe need to talk. A modal window with a header, a scrolling body and a footer. Open it from a template or straight from code.
Installation
Usage
<script setup lang="ts">
import { Button } from '@/components/ui/button'
import {
Dialog,
DialogBody,
DialogClose,
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
DialogTitle,
DialogTrigger,
} from '@/components/ui/dialog'
</script>
<template>
<Dialog>
<DialogTrigger as-child>
<Button>Edit profile</Button>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Edit profile</DialogTitle>
<DialogDescription>Changes are saved when you press Save.</DialogDescription>
</DialogHeader>
<DialogBody>
<!-- the content -->
</DialogBody>
<DialogFooter>
<DialogClose as-child>
<Button>Save</Button>
</DialogClose>
</DialogFooter>
</DialogContent>
</Dialog>
</template>
Dialog: holds the state;v-model:openopens it from codeDialogTrigger: opens itDialogContent: the window, with an overlay and a close buttonDialogHeader,DialogBody,DialogFooter: the three partsDialogClose: wrap any button in it to make it close the dialog
Putting a form inside? Wrap the parts in <form class="contents">, so the layout and scrolling keep working.
Escape or a click outside closes it. Focus stays inside while it's open, lands on the first field rather than the close button, and returns to the trigger when the dialog closes. More on overlays.
Too much content? The body scrolls, and the header and footer stay put.
Examples
Long content
Once the window reaches the edge of the screen, the body scrolls between the header and the footer.
Scroll area
Want the thin ScrollArea scrollbar instead of the browser's? Let the scroll area take the rest of the window with flex-1: the window grows with the list until it reaches the edge of the screen, and the list scrolls from there.
Scrolling overlay
Long read? Use DialogScrollContent instead of DialogContent: the window keeps its full height, and the whole thing scrolls like a page.
Don't turn off modal here, or nothing renders at all.
Fullscreen
No special prop, just classes. Add these to DialogContent, and the window fills the screen:
inset-0 size-full max-h-none max-w-none translate-none rounded-none border-0
Not dismissible
No escape. Literally. Prevent escape-key-down and interact-outside on DialogContent, and only a button inside can close it. Add :show-close-button="false" to hide the close button too.
Nested
Yo dawg, I heard you like dialogs. Open one from inside another, and it stacks on top. Only the top one dims the page, and Escape or a click outside closes only that one.
In the demo, the inner dialog confirms a change, and the first one stays open with the result.
Custom layout
The parts are plain elements with classes, so any of them can be restyled or left out. This confirmation centres its header and drops the close button.
Controlled
Without a trigger, bind v-model:open and open the dialog from anywhere in the component. Here it opens from a menu item. To open a dialog without placing it in a template at all, see From code.
quarterly-report.pdf
From code
No template? No problem. Open a dialog from a store, a router guard or a callback, and await how it closed.
Setup
Install it once:
// main.ts
import { createApp } from 'vue'
import { createDialogs } from '@/components/ui/dialog'
import App from './App.vue'
createApp(App).use(createDialogs()).mount('#app')
In Nuxt, use a plugin:
// plugins/dialogs.ts
import { createDialogs } from '@/components/ui/dialog'
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(createDialogs())
})
Add one DialogHost to the root component. Dialogs opened from code render there, so they can use the router, i18n and stores:
<!-- App.vue -->
<script setup lang="ts">
import { DialogHost } from '@/components/ui/dialog'
</script>
<template>
<RouterView />
<DialogHost />
</template>
Opening a dialog
Write a component that renders DialogContent, just like in a template. useDialogContext() gives it close(value) and dismiss():
<!-- DeleteFileDialog.vue -->
<script setup lang="ts">
import { Button } from '@/components/ui/button'
import {
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
DialogTitle,
useDialogContext,
} from '@/components/ui/dialog'
const props = defineProps<{ name: string }>()
const { close, dismiss } = useDialogContext()
</script>
<template>
<DialogContent class="max-w-sm">
<DialogHeader>
<DialogTitle>Delete {{ props.name }}?</DialogTitle>
<DialogDescription>The file moves to the bin for 30 days.</DialogDescription>
</DialogHeader>
<DialogFooter>
<Button variant="outline" color="neutral" @click="dismiss()">Cancel</Button>
<Button color="destructive" @click="close()">Delete</Button>
</DialogFooter>
</DialogContent>
</template>
Then open it and wait:
const result = await openDialog(DeleteFileDialog, { name: 'report.pdf' })
if (result.ok) deleteFile()
The promise never rejects. After close(value), result.ok is true and you get result.value. Otherwise it's false, and result.reason says why:
report.pdf is in your files.
| Reason | What happened |
|---|---|
escape | Escape was pressed |
outside | A click or focus landed outside |
swipe | A drawer was swiped away |
close-button | A DialogClose was pressed |
programmatic | dismiss() was called |
close-all | closeAllDialogs() was called |
unmount | DialogHost unmounted |
no-host | No service or no DialogHost. Resolves at once, with a console warning |
error | It failed to render. The error also goes to app.config.errorHandler |
The promise is also a handle: isOpen, close(value) and dismiss() work from outside, and patch(props) updates the props on the fly. Only the first close counts.
One dialog, many calls
defineDialog(component, { props }) sets the component and default props once. Each open(props) merges new props over the defaults. Calling open() while the dialog is already open returns the same one, not a second window. isOpen and dismiss() work from anywhere.
In the demo, the caller updates the progress while the dialog is open:
12 photos selected.
Closing with a value? Type it on both sides: useDialogContext<string>() inside, open<string>() outside. openDialog<string>() works too, but then the props go unchecked. defineDialog checks both.
Waiting for work
While loading from useDialogContext() is true, Escape, outside clicks and DialogClose do nothing. Only close() or dismiss() can close it. Disable the buttons too, so nobody starts the work twice.
Aurora
Keeping state
With keepMounted: true, a defined dialog is hidden instead of removed, so its state survives until the next open. Each open still gets its own promise.
Nothing sent yet.
Closing everything
closeAllDialogs() closes them all. Dialogs survive navigation, so to close them on every route change:
router.afterEach(() => closeAllDialogs())
API Reference
Every part except Dialog, which renders no element, accepts class, merged over its own classes with tailwind-merge. On DialogContent and DialogScrollContent it styles the window, so a width class such as max-w-2xl resizes it.
Dialog
| Prop | Default | Type and description |
|---|---|---|
| open | — | booleanWhether it is open, bound with |
| defaultOpen | — | booleanWhether the dialog starts open when |
| modal | — | booleanShuts the page while open: focus stays in the window, the page does not scroll, and the overlay takes outside clicks. Off, the page stays live and has no overlay. |
| unmountOnHide | — | booleanRemoves the window from the DOM while closed. Turn it off to keep its state between openings. |
| Event | Payload and description |
|---|---|
| update:open | [value: boolean]Fires when the dialog opens or closes. |
| Slot | Scope and description |
|---|---|
| default | { open: boolean; close: () => void; }The trigger and the content. Receives |
DialogTrigger
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a button, merging the trigger's attributes and behaviour onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The trigger's content, or with |
DialogContent
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the window mounted while closed, for animating it with a JavaScript library. |
| disableOutsidePointerEvents | — | booleanBlocks pointer events outside the window. On by default in a modal dialog; a non-modal dialog ignores it. |
| asChild | — | booleanNot supported on this part: the window always adds its own close button, and core adds the hidden title fallback, so there is more than one node to merge onto a single child. |
| as | — | AsTag | ComponentThe element or component to render. |
| showCloseButton | true | booleanShows a close button in the window's top corner. It comes last in the tab order, so a form's first field takes focus on open. |
| Event | Payload and description |
|---|---|
| escapeKeyDown | [event: KeyboardEvent]Fires on Escape. Call |
| pointerDownOutside | [event: PointerDownOutsideEvent]Fires on a pointer press outside. Call |
| focusOutside | [event: FocusOutsideEvent]Fires when focus moves outside. Call |
| interactOutside | [event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. Call |
| openAutoFocus | [event: Event]Fires when focus moves into the window on open. Call |
| closeAutoFocus | [event: Event]Fires when focus returns to the trigger on close. Call |
| Slot | Scope and description |
|---|---|
| default | {}The window's parts: |
DialogScrollContent
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the window mounted while closed, for animating it with a JavaScript library. |
| disableOutsidePointerEvents | — | booleanBlocks pointer events outside the window. On by default in a modal dialog; a non-modal dialog ignores it. |
| asChild | — | booleanNot supported on this part: the window always adds its own close button, and core adds the hidden title fallback, so there is more than one node to merge onto a single child. |
| as | — | AsTag | ComponentThe element or component to render. |
| showCloseButton | true | booleanShows a close button in the window's top corner. It comes last in the tab order, so a form's first field takes focus on open. |
| Event | Payload and description |
|---|---|
| escapeKeyDown | [event: KeyboardEvent]Fires on Escape. Call |
| pointerDownOutside | [event: PointerDownOutsideEvent]Fires on a pointer press outside. A press on the overlay's scrollbar does not close it. Call |
| focusOutside | [event: FocusOutsideEvent]Fires when focus moves outside. Call |
| interactOutside | [event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. Call |
| openAutoFocus | [event: Event]Fires when focus moves into the window on open. Call |
| closeAutoFocus | [event: Event]Fires when focus returns to the trigger on close. Call |
| Slot | Scope and description |
|---|---|
| default | {}The window's parts. The window keeps its full height and the overlay scrolls. |
DialogOverlay
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the overlay mounted while closed, for animating it with a JavaScript library. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}Content placed on the overlay, as |
DialogHeader
| Slot | Scope and description |
|---|---|
| default | {}The title and description. Keeps clear of the close button while there is one. |
DialogBody
| Slot | Scope and description |
|---|---|
| default | {}The content between the header and the footer. Scrolls once the window reaches the height of the screen. |
DialogFooter
| Slot | Scope and description |
|---|---|
| default | {}The buttons, stacked on narrow screens and in a row from 640px up, at the end. |
DialogTitle
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The title, which names the dialog for screen readers. |
DialogDescription
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The description, which describes the dialog for screen readers. |
DialogClose
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The element that closes the dialog, usually a |
Props
- open
booleanWhether it is open, bound withv-model:open.- defaultOpen
booleanWhether the dialog starts open whenv-model:openis not used.- modal
booleanShuts the page while open: focus stays in the window, the page does not scroll, and the overlay takes outside clicks. Off, the page stays live and has no overlay.- unmountOnHide
booleanRemoves the window from the DOM while closed. Turn it off to keep its state between openings.
Emits
- update:open
[value: boolean]Fires when the dialog opens or closes.
Slots
- default
{ open: boolean; close: () => void; }The trigger and the content. Receivesopenandclose.
Props
- asChild
booleanRender the single child instead of a button, merging the trigger's attributes and behaviour onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The trigger's content, or withas-childthe element that opens the dialog.
Props
- forceMount
booleanKeeps the window mounted while closed, for animating it with a JavaScript library.- disableOutsidePointerEvents
booleanBlocks pointer events outside the window. On by default in a modal dialog; a non-modal dialog ignores it.- asChild
booleanNot supported on this part: the window always adds its own close button, and core adds the hidden title fallback, so there is more than one node to merge onto a single child.- as
AsTag | ComponentThe element or component to render.- showCloseButton
true booleanShows a close button in the window's top corner. It comes last in the tab order, so a form's first field takes focus on open.
Emits
- escapeKeyDown
[event: KeyboardEvent]Fires on Escape. CallpreventDefault()to keep it open.- pointerDownOutside
[event: PointerDownOutsideEvent]Fires on a pointer press outside. CallpreventDefault()to keep it open.- focusOutside
[event: FocusOutsideEvent]Fires when focus moves outside. CallpreventDefault()to keep it open.- interactOutside
[event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. CallpreventDefault()to keep it open.- openAutoFocus
[event: Event]Fires when focus moves into the window on open. CallpreventDefault()to keep focus where it is.- closeAutoFocus
[event: Event]Fires when focus returns to the trigger on close. CallpreventDefault()to keep focus where it is.
Slots
- default
{}The window's parts:DialogHeader,DialogBodyandDialogFooter, or a layout of your own.
Props
- forceMount
booleanKeeps the window mounted while closed, for animating it with a JavaScript library.- disableOutsidePointerEvents
booleanBlocks pointer events outside the window. On by default in a modal dialog; a non-modal dialog ignores it.- asChild
booleanNot supported on this part: the window always adds its own close button, and core adds the hidden title fallback, so there is more than one node to merge onto a single child.- as
AsTag | ComponentThe element or component to render.- showCloseButton
true booleanShows a close button in the window's top corner. It comes last in the tab order, so a form's first field takes focus on open.
Emits
- escapeKeyDown
[event: KeyboardEvent]Fires on Escape. CallpreventDefault()to keep it open.- pointerDownOutside
[event: PointerDownOutsideEvent]Fires on a pointer press outside. A press on the overlay's scrollbar does not close it. CallpreventDefault()to keep it open.- focusOutside
[event: FocusOutsideEvent]Fires when focus moves outside. CallpreventDefault()to keep it open.- interactOutside
[event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. CallpreventDefault()to keep it open.- openAutoFocus
[event: Event]Fires when focus moves into the window on open. CallpreventDefault()to keep focus where it is.- closeAutoFocus
[event: Event]Fires when focus returns to the trigger on close. CallpreventDefault()to keep focus where it is.
Slots
- default
{}The window's parts. The window keeps its full height and the overlay scrolls.
Props
- forceMount
booleanKeeps the overlay mounted while closed, for animating it with a JavaScript library.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}Content placed on the overlay, asDialogScrollContentdoes with its window.
Slots
- default
{}The title and description. Keeps clear of the close button while there is one.
Slots
- default
{}The content between the header and the footer. Scrolls once the window reaches the height of the screen.
Slots
- default
{}The buttons, stacked on narrow screens and in a row from 640px up, at the end.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The title, which names the dialog for screen readers.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The description, which describes the dialog for screen readers.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The element that closes the dialog, usually aButtonwithas-child.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| dialog-trigger | data-state | The element that opens the dialog. |
| dialog-overlay | data-state | The layer behind the window that dims the page and takes outside presses. Under another open dialog it turns clear, so a stack dims the page once. |
| dialog-content | data-state | The window. |
| dialog-header | — | The title and description. |
| dialog-title | — | The title. |
| dialog-description | — | The description. |
| dialog-body | — | The scrolling middle. |
| dialog-footer | — | The buttons at the bottom. |
| dialog-close | — | The close button, or any DialogClose. |
Accessibility
The dialog's name comes from its DialogTitle and its description from its DialogDescription. Always give it a title: without one, screen readers announce an unnamed dialog. To name a dialog without showing the title, wrap the title in VisuallyHidden from reka-ui. The description is optional. When either is missing, the window renders an empty hidden one in its place, so Reka UI does not warn in the console.
| Key | Action |
|---|---|
| Tab / Shift + Tab | Moves to the next or previous control in the window, wrapping around inside it. |
| Escape | Closes the dialog and returns focus to the element that opened it. While an input method is composing text, Escape ends the composition instead. |