Dialog - Vant 4

Dialog

💬 Capture attention with elegant modal dialogs that users can't ignore!

🎭 Intro

Meet the Dialog component - your go-to solution for creating impactful user interactions! 🚀 Whether you need to alert users, confirm critical actions, or gather input, this versatile modal component delivers a polished experience every time. With both functional and component-based approaches, you have the flexibility to implement dialogs exactly how you want them! ✨

📦 Install

Get your Dialog component ready in no time! Register it globally via app.use and start creating engaging user interactions immediately! 🎯 Check out our Component Registration guide for more installation options.

import { createApp } from'vue'; import { Dialog } from'vant'; const app = createApp(); app.use(Dialog);

⚡ Function Call

Experience the magic of instant dialogs! Vant provides powerful utility functions that let you create beautiful dialogs with just a single function call - no template setup required! 🪄

For example, calling the showDialog function will render a Dialog directly in the page like magic! ✨

import { showDialog } from'vant'; showDialog({ message: 'Alert' });

🎨 Usage

🚨 Alert Dialog

Perfect for delivering important messages to your users! 📢 This simple yet effective dialog includes just one confirm button, making it ideal for notifications and alerts.

import { showDialog } from'vant'; showDialog({ title: 'Title', message: 'Content', }).then(() => { // on close });

❓ Confirm Dialog

Need user confirmation before proceeding? This powerful dialog includes both confirm and cancel buttons, giving users full control over their decisions! 🤔💭

import { showConfirmDialog } from'vant'; showConfirmDialog({ title: 'Title', message: 'Content', }) .then(() => { // on confirm }) .catch(() => { // on cancel });

🎪 Round Button Style

Transform your dialogs with a modern, sleek appearance! Setting the theme option to round-button creates beautifully rounded buttons that add a contemporary touch to your interface. 🌟

import { showDialog } from'vant'; showDialog({ title: 'Title', message: 'Content', theme: 'round-button', }).then(() => { // on close });

⏳ Async Close

Take full control over dialog closing behavior! Perfect for validating user input or performing async operations before allowing the dialog to close. 🔄

import { showConfirmDialog } from'vant'; const beforeClose = (action) => new Promise((resolve) => { setTimeout(() => { if (action === 'confirm') { resolve(true); } else { // Prevent the default behavior resolve(false); } }, 1000); }); showConfirmDialog({ title: 'Title', message: 'Content', beforeClose, });

🧩 Use Dialog Component

Want complete creative control? Use the Dialog component directly to embed custom content, images, forms, or any Vue components within your dialogs! 🎨 Perfect for complex interactions that go beyond simple text messages.

<van-dialog v-model:show="show" title="Title" show-cancel-button> <img src="https://fastly.jsdelivr.net/npm/@vant/assets/apple-3.jpeg" /> </van-dialog>

import { ref } from'vue'; export default { setup() { const show = ref(false); return { show }; }, };

📚 API

🛠️ Methods

Vant exports these powerful Dialog utility functions to make your life easier! 🚀

Methods	Attribute	Return value	Description
showDialog	options	Promise<void>	Show dialog
showConfirmDialog	options	Promise<void>	Show confirm dialog
closeDialog	-	void	Close dialog
setDialogDefaultOptions	options	void	Set default options of all dialogs
resetDialogDefaultOptions	-	void	Reset default options of all dialogs

DialogOptions

Attribute	Description	Type	Default
title	Title	string	-
width	Dialog width	*number	string*
message	Message	*string	() => JSX.ELement*
messageAlign	Message text align, can be set to left``right	string	center
theme	Theme style, can be set to round-button	string	default
className	Custom className	*string	Array
showConfirmButton	Whether to show confirm button	boolean	true
showCancelButton	Whether to show cancel button	boolean	false
cancelButtonText	Cancel button text	string	Cancel
cancelButtonColor	Cancel button color	string	black
cancelButtonDisabled	Whether to disable cancel button	boolean	false
confirmButtonText	Confirm button text	string	Confirm
confirmButtonColor	Confirm button color	string	#ee0a24

| confirmButtonDisabled | Whether to disable confirm button | boolean | false | | destroyOnClose v4.9.18 | Whether to destroy content when closed | boolean | false | | overlay | Whether to show overlay | boolean | true | | overlayClass | Custom overlay class | string | Array | object | - | | overlayStyle | Custom overlay style | object | - | | closeOnPopstate | Whether to close when popstate | boolean | true | | closeOnClickOverlay | Whether to close when overlay is clicked | boolean | false | | lockScroll | Whether to lock body scroll | boolean | true | | allowHtml | Whether to allow HTML rendering in message | boolean | false | | beforeClose | Callback function before close | (action: string) => boolean | Promise<boolean> | - | | transition | Transition, equivalent to name prop of transition | string | - |

| teleport | Specifies a target element where Dialog will be mounted | string | Element | body | | keyboardEnabled | Whether to enable keyboard capabilities. When displaying the confirm and cancel buttons, the keyboard's Enter and Esc will call the confirm and cancel functions by default | boolean | true |

Props

Attribute	Description	Type	Default
v-model:show	Whether to show dialog	boolean	-
title	Title	string	-
width	Width	*number	string*
message	Message	*string	() => JSX.ELement*
message-align	Message align, can be set to left``right``justify	string	center
theme	Theme style, can be set to round-button	string	default
show-confirm-button	Whether to show confirm button	boolean	true
show-cancel-button	Whether to show cancel button	boolean	false
cancel-button-text	Cancel button text	string	Cancel
cancel-button-color	Cancel button color	string	black
cancel-button-disabled	Whether to disable cancel button	boolean	false
confirm-button-text	Confirm button text	string	Confirm
confirm-button-color	Confirm button color	string	#ee0a24

| confirm-button-disabled | Whether to disable confirm button | boolean | false | | destroy-on-close v4.9.18 | Whether to destroy content when closed | boolean | false | | z-index | Set the z-index to a fixed value | number | string | 2000+ | | overlay | Whether to show overlay | boolean | true | | overlay-class | Custom overlay class | string | - | | overlay-style | Custom overlay style | object | - | | close-on-popstate | Whether to close when popstate | boolean | true | | close-on-click-overlay | Whether to close when overlay is clicked | boolean | false | | lazy-render | Whether to lazy render util appeared | boolean | true | | lock-scroll | Whether to lock background scroll | boolean | true | | allow-html | Whether to allow HTML rendering in message | boolean | false | | before-close | Callback function before close | (action: string) => boolean | Promise<boolean> | - | | transition | Transition, equivalent to name prop of transition | string | - |

| teleport | Specifies a target element where Dialog will be mounted | string | Element | - | | keyboard-enabled | Whether to enable keyboard capabilities. When displaying the confirm and cancel buttons, the keyboard's Enter and Esc will call the confirm and cancel functions by default | boolean | true |

Events

Event	Description	Parameters
confirm	Emitted when the confirm button is clicked	-
cancel	Emitted when the cancel button is clicked	-
open	Emitted when opening Dialog	-
close	Emitted when closing Dialog	-
opened	Emitted when Dialog is opened	-
closed	Emitted when Dialog is closed	-

Slots

Name	Description
default	Custom message
title	Custom title
footer	Custom footer

Types

The component exports the following type definitions:

importtype { DialogProps, DialogTheme, DialogMessage, DialogOptions, DialogMessageAlign, } from'vant';

Theming

CSS Variables

The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.

Name	Default Value	Description
--van-dialog-width	320px	-
--van-dialog-small-screen-width	90%	-
--van-dialog-font-size	var(--van-font-size-lg)	-
--van-dialog-transition	var(--van-duration-base)	-
--van-dialog-radius	16px	-
--van-dialog-background	var(--van-background-2)	-
--van-dialog-header-font-weight	var(--van-font-bold)	-
--van-dialog-header-line-height	24px	-
--van-dialog-header-padding-top	26px	-
--van-dialog-header-isolated-padding	var(--van-padding-lg) 0	-
--van-dialog-message-padding	var(--van-padding-lg)	-
--van-dialog-message-font-size	var(--van-font-size-md)	-
--van-dialog-message-line-height	var(--van-line-height-md)	-
--van-dialog-message-max-height	60vh	-
--van-dialog-has-title-message-text-color	var(--van-gray-7)	-
--van-dialog-has-title-message-padding-top	var(--van-padding-xs)	-
--van-dialog-button-height	48px	-
--van-dialog-round-button-height	36px	-
--van-dialog-confirm-button-text-color	var(--van-primary-color)	-

## 🔗 Related Docs

- [Toast](./toast) - Show lightweight feedback messages
- [Popup](./popup) - Create custom modal overlays
- [ActionSheet](./action-sheet) - Present action options to users
- [Notify](./notify) - Display notification messages
- [Overlay](./overlay) - Create backdrop overlays
- [Button](./button) - Interactive button components
- [ConfigProvider](./config-provider) - Global configuration
- [Advanced Usage](./advanced-usage) - Advanced component techniques