Informs users while preserving the current page state.


This component requires the <client-only></client-only> wrap when used in SSR (eg: Nuxt) and SSG (eg: VitePress).

Basic usage

Dialog pops up a dialog box, and it's quite customizable.


before-close only works when user clicks the close icon or the backdrop. If you have buttons that close the Dialog in the footer named slot, you can add what you would do with before-close in the buttons' click event handler.

Customized Content

The content of Dialog can be anything, even a table or a form. This example shows how to use Element Plus Table and Form with Dialog.

Customized Header

The header slot can be used to customize the area where the title is displayed. In order to maintain accessibility, use the title attribute in addition to using this slot, or use the titleId slot property to specify which element should be read out as the dialog title.

Nested Dialog

If a Dialog is nested in another Dialog, append-to-body is required.

Centered content

Dialog's content can be centered.


The content of Dialog is lazily rendered, which means the default slot is not rendered onto the DOM until it is firstly opened. Therefore, if you need to perform a DOM manipulation or access a component using ref, do it in the open event callback.

Align Center dialog

Open dialog from the center of the screen.

Destroy on Close

When this is feature is enabled, the content under default slot will be destroyed with a v-if directive. Enable this when you have perf concerns.

Draggable Dialog

Try to drag the header part.


When using modal = false, please make sure that append-to-body was set to true, because Dialog was positioned by position: relative, when modal gets removed, Dialog will position itself based on the current position in the DOM, instead of Document.Body, thus the style will be messed up.



model-value / v-modelvisibility of Dialogboolean
titletitle of Dialog. Can also be passed with a named slot (see the following table)string''
widthwidth of Dialog, default is 50%string / number''
fullscreenwhether the Dialog takes up full screenbooleanfalse
topvalue for margin-top of Dialog CSS, default is 15vhstring''
modalwhether a mask is displayedbooleantrue
modal-classcustom class names for maskstring
append-to-bodywhether to append Dialog itself to body. A nested Dialog should have this attribute set to truebooleanfalse
append-to 2.4.3which element the Dialog appends to. Will override append-to-bodystringbody
lock-scrollwhether scroll of body is disabled while Dialog is displayedbooleantrue
custom-class deprecatedcustom class names for Dialogstring''
open-delaythe Time(milliseconds) before opennumber0
close-delaythe Time(milliseconds) before closenumber0
close-on-click-modalwhether the Dialog can be closed by clicking the maskbooleantrue
close-on-press-escapewhether the Dialog can be closed by pressing ESCbooleantrue
show-closewhether to show a close buttonbooleantrue
before-closecallback before Dialog closes, and it will prevent Dialog from closing, use done to close the dialogFunction
draggableenable dragging feature for Dialogbooleanfalse
overflow 2.5.4draggable Dialog can overflow the viewportbooleanfalse
centerwhether to align the header and footer in centerbooleanfalse
align-center 2.2.16whether to align the dialog both horizontally and verticallybooleanfalse
destroy-on-closedestroy elements in Dialog when closedbooleanfalse
close-iconcustom close icon, default is Closestring / Component
z-indexsame as z-index in native CSS, z-order of dialognumber
header-aria-level a11yheader's aria-level attributestring2


custom-class has been deprecated, and will be removed in 2.4.0, please use class.


content of Dialog
headercontent of the Dialog header; Replacing this removes the title, but does not remove the close button.
title deprecatedworks the same as the header slot. Use that instead.
footercontent of the Dialog footer


title has been deprecated, and will be removed in 2.4.0, please use header.


opentriggers when the Dialog opensFunction
openedtriggers when the Dialog opening animation endsFunction
closetriggers when the Dialog closesFunction
closedtriggers when the Dialog closing animation endsFunction
open-auto-focustriggers after Dialog opens and content focusedFunction
close-auto-focustriggers after Dialog closed and content focusedFunction


Using dialog in SFC, the scope style does not take effect.

Typical issue: #10515

PS: Since the dialog is rendered using Teleport, the style of the root node is recommended to be written globally.

When the dialog is displayed and hidden, there is a situation where the page elements are displaced back and forth.

Typical issue: #10481

PS: It is recommended to place the scroll area inside a vue mounted node, e.g. <div id="app" />, and use the overflow: hidden style for the body.