Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Overlays

Dialog

A native top-layer modal with a stationary header and footer and a scrollable body.

Last changed in version 0.13.4: Keep dialogs compact when a stylesheet resets their height.

Interactive showcase

Edit profile

Update your public details.

Install

Run in your project
bunx --bun @getweini/cli@latest add dialog

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Settings

Put your settings here.

Vue
<script setup lang="ts">
import Dialog from './components/ui/dialog/Dialog.vue'
import DialogBody from './components/ui/dialog/DialogBody.vue'
import DialogClose from './components/ui/dialog/DialogClose.vue'
import DialogContent from './components/ui/dialog/DialogContent.vue'
import DialogFooter from './components/ui/dialog/DialogFooter.vue'
import DialogHeader from './components/ui/dialog/DialogHeader.vue'
import DialogTitle from './components/ui/dialog/DialogTitle.vue'
import DialogTrigger from './components/ui/dialog/DialogTrigger.vue'
</script>

<template>
  <Dialog>
    <DialogTrigger>Open settings</DialogTrigger>
    <DialogContent>
      <DialogHeader><DialogTitle>Settings</DialogTitle></DialogHeader>
      <DialogBody><p>Put your settings here.</p></DialogBody>
      <DialogFooter><DialogClose>Done</DialogClose></DialogFooter>
    </DialogContent>
  </Dialog>
</template>

Use DialogHeader’s #actions slot for an optional close control. Set persistent on DialogContent when backdrop clicks should leave the form open; Escape and close buttons still dismiss it. Fullscreen keeps the header and footer visible while DialogBody scrolls.

When to use it

Edit an object

Keep a longer form in a scrolling body with stationary title and actions.

Inspect details

Open a modal view when the user needs to focus on one record.

More examples

Edit profile

The native dialog manages modality and restores trigger focus.

Edit profile
<script setup lang="ts">
import Dialog from './components/ui/dialog/Dialog.vue'
import DialogBody from './components/ui/dialog/DialogBody.vue'
import DialogClose from './components/ui/dialog/DialogClose.vue'
import DialogContent from './components/ui/dialog/DialogContent.vue'
import DialogDescription from './components/ui/dialog/DialogDescription.vue'
import DialogFooter from './components/ui/dialog/DialogFooter.vue'
import DialogHeader from './components/ui/dialog/DialogHeader.vue'
import DialogTitle from './components/ui/dialog/DialogTitle.vue'
import DialogTrigger from './components/ui/dialog/DialogTrigger.vue'
</script>
<template>
  <Dialog>
    <DialogTrigger>Edit profile</DialogTrigger>
    <DialogContent size="lg">
      <DialogHeader>
        <DialogTitle>Edit profile</DialogTitle>
        <DialogDescription>Update your public details.</DialogDescription>
      </DialogHeader>
      <DialogBody>
        <label>Name&nbsp;<input name="name"></label>
      </DialogBody>
      <DialogFooter><DialogClose>Done</DialogClose></DialogFooter>
    </DialogContent>
  </Dialog>
</template>

Persistent review

Persistent content stays open on backdrop clicks but still responds to Escape.

Persistent review
<script setup lang="ts">
import Dialog from './components/ui/dialog/Dialog.vue'
import DialogBody from './components/ui/dialog/DialogBody.vue'
import DialogClose from './components/ui/dialog/DialogClose.vue'
import DialogContent from './components/ui/dialog/DialogContent.vue'
import DialogFooter from './components/ui/dialog/DialogFooter.vue'
import DialogHeader from './components/ui/dialog/DialogHeader.vue'
import DialogTitle from './components/ui/dialog/DialogTitle.vue'
import DialogTrigger from './components/ui/dialog/DialogTrigger.vue'
</script>
<template>
  <Dialog>
    <DialogTrigger>Review changes</DialogTrigger>
    <DialogContent persistent>
      <DialogHeader><DialogTitle>Review changes</DialogTitle></DialogHeader>
      <DialogBody><p>Check these changes before you continue.</p></DialogBody>
      <DialogFooter><DialogClose>Close review</DialogClose></DialogFooter>
    </DialogContent>
  </Dialog>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Dialog

Complete API for Dialog
NameType or signatureDefaultWhat it does
openmodelboolean | undefinedNot setCurrent open state. Use v-model:open to keep it in sync with your page.
defaultOpenpropboolean | undefinedfalseStarting open state when the parent does not control open.
disabledpropboolean | undefinedfalsePrevent interaction and show the disabled state.
update:openevent[open: boolean]—Requests a new open value from the parent.
openChangeevent[open: boolean]—Emitted after this value or state changes.
defaultslot() => unknownRequiredContent shown inside Dialog.
openexposed() => void—Open this component from application code.
closeexposed() => void—Close this component from application code.

DialogBody

Complete API for DialogBody
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside DialogBody.

DialogClose

Complete API for DialogClose
NameType or signatureDefaultWhat it does
asChildpropboolean | undefinedNot setUse one child element as the control instead of adding another wrapper.
defaultslot{}OptionalContent shown inside DialogClose.

DialogContent

Complete API for DialogContent
NameType or signatureDefaultWhat it does
fullscreenpropboolean | undefinedfalseFill the available viewport with the dialog content.
sizepropDialogSize | undefined"md"Choose the visual size. Medium is the usual default where available.
dismissOnBackdroppropboolean | undefinedtrueAllow a click outside the dialog content to close it.
persistentpropboolean | undefinedfalseKeep the dialog open when the backdrop is clicked.
defaultslot{ close: () => void; }OptionalContent shown inside DialogContent.

DialogDescription

Complete API for DialogDescription
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside DialogDescription.

DialogFooter

Complete API for DialogFooter
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside DialogFooter.

DialogHeader

Complete API for DialogHeader
NameType or signatureDefaultWhat it does
defaultslot() => unknownRequiredContent shown inside DialogHeader.
actionsslot(() => unknown) | undefinedOptionalContent for the actions area of DialogHeader.

DialogTitle

Complete API for DialogTitle
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside DialogTitle.

DialogTrigger

Complete API for DialogTrigger
NameType or signatureDefaultWhat it does
disabledpropboolean | undefinedfalsePrevent interaction and show the disabled state.
asChildpropboolean | undefinedNot setUse one child element as the control instead of adding another wrapper.
defaultslot{}OptionalContent shown inside DialogTrigger.
Public type definitions
Public types
// packages/frameworks/vue/components/dialog/types.ts
// ------- TYPES -------

export type DialogSize = 'sm' | 'md' | 'lg' | 'xl'

export interface DialogProps {
  open?: boolean
  defaultOpen?: boolean
  disabled?: boolean
}

export interface DialogContentProps {
  fullscreen?: boolean
  size?: DialogSize
  dismissOnBackdrop?: boolean
  persistent?: boolean
}

export interface DialogTriggerProps {
  disabled?: boolean
  asChild?: boolean
}

export interface DialogCloseProps {
  asChild?: boolean
}

Implementation notes

  • Place substantial content inside DialogBody; it is the independently scrolling row.
  • Persistent takes precedence over dismissOnBackdrop, but Escape and explicit close controls still work.

Accessibility and localization

  • Provide DialogTitle or an explicit accessible name.
  • Use data-dialog-initial-focus on the control that should receive initial focus when the default order is unsuitable.

Source contract and editing guidance