Dialog
Informs users while preserving the current page state.
Basic usage
Dialog pops up a dialog box, and it's quite customizable.
TIP
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.
TIP
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.
TIP
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.
Fullscreen
Set the fullscreen attribute to open fullscreen dialog.
TIP
If fullscreen is true, width top draggable attributes don't work.
Modal
Setting modal to false will hide modal (overlay) of dialog.
Starting from version 2.10.5, modal-penetrable attribute is added, which can be penetrable.
Custom Animation 2.10.5
Customize dialog animation through the transition attribute, which accepts either:
Transition name (string)
Vue transition configuration (object)
TIP
Animation classes are dynamically generated based on the transition name. For granular control over animation behavior, you may explicitly define these classes. Refer to custom-transition-classes for details.
Events
Open developer console (ctrl + shift + J), to see order of events.
API
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| model-value / v-model | visibility of Dialog | boolean | false |
| title | title of Dialog. Can also be passed with a named slot (see the following table) | string | '' |
| width | width of Dialog, default is 50% | string / number | '' |
| fullscreen | whether the Dialog takes up full screen | boolean | false |
| top | value for margin-top of Dialog CSS, default is 15vh | string | '' |
| modal | whether a mask is displayed | boolean | true |
| modal-penetrable 2.10.5 | whether the mask is penetrable. The modal attribute must be false. | boolean | false |
| modal-class | custom class names for mask | string | — |
| header-class 2.9.3 | custom class names for header wrapper | string | — |
| body-class 2.9.3 | custom class names for body wrapper | string | — |
| footer-class 2.9.3 | custom class names for footer wrapper | string | — |
| append-to-body | whether to append Dialog itself to body. A nested Dialog should have this attribute set to true | boolean | false |
| append-to 2.4.3 | which element the Dialog appends to. Will override append-to-body | CSSSelector / HTMLElement | body |
| lock-scroll | whether scroll of body is disabled while Dialog is displayed | boolean | true |
| open-delay | the Time(milliseconds) before open | number | 0 |
| close-delay | the Time(milliseconds) before close | number | 0 |
| close-on-click-modal | whether the Dialog can be closed by clicking the mask | boolean | true |
| close-on-press-escape | whether the Dialog can be closed by pressing ESC | boolean | true |
| show-close | whether to show a close button | boolean | true |
| before-close | callback before Dialog closes, and it will prevent Dialog from closing, use done to close the dialog | Function | — |
| draggable | enable dragging feature for Dialog | boolean | false |
| overflow 2.5.4 | draggable Dialog can overflow the viewport | boolean | false |
| center | whether to align the header and footer in center | boolean | false |
| align-center 2.2.16 | whether to align the dialog both horizontally and vertically | boolean | false |
| destroy-on-close | destroy elements in Dialog when closed | boolean | false |
| close-icon | custom close icon, default is Close | string / Component | — |
| z-index | same as z-index in native CSS, z-order of dialog | number | — |
| header-aria-level a11y | header's aria-level attribute | string | 2 |
| transition 2.10.5 | custom transition configuration for dialog animation. Can be a string (transition name) or an object with Vue transition props | string / object | dialog-fade |
| custom-class deprecated | custom class names for Dialog | string | '' |
WARNING
custom-class has been deprecated, and will be removed in 2.4.0, please use class.
Slots
| Name | Description |
|---|---|
| default | default content of Dialog |
| header | content of the Dialog header; Replacing this removes the title, but does not remove the close button. |
| footer | content of the Dialog footer |
| title deprecated | works the same as the header slot. Use that instead. |
WARNING
title has been deprecated, and will be removed in 3.0.0, please use header.
Events
| Name | Description | Type |
|---|---|---|
| open | triggers when the Dialog opens | Function |
| opened | triggers when the Dialog opening animation ends | Function |
| close | triggers when the Dialog closes | Function |
| closed | triggers when the Dialog closing animation ends | Function |
| open-auto-focus | triggers after Dialog opens and content focused | Function |
| close-auto-focus | triggers after Dialog closed and content focused | Function |
Exposes
| Name | Description | Type |
|---|---|---|
| resetPosition 2.8.1 | reset position | Function |
| handleClose 2.9.8 | close dialog | Function |
FAQ
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.