Intro

A modal box pops up on the page, which is often used for message prompts, message confirmation, or to complete specific interactive operations in the current page. It supports two methods: function call and component call.

Install

import { createApp } from 'vue';
import { Dialog } from 'vant';

const app = createApp();
app.use(Dialog);

Alert dialog

Used to prompt for some messages, only including one confirm button.

Dialog.alert({
  title: 'Title',
  message: 'Content',
}).then(() => {
  // on close
});

Dialog.alert({
  message: 'Content',
}).then(() => {
  // on close
});

Confirm dialog

Used to confirm some messages, including a confirm button and a cancel button.

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

Round Button Style

Use round button style.

Dialog.alert({
  title: 'Title',
  message: 'Content',
  theme: 'round-button',
}).then(() => {
  // on close
});

Dialog.alert({
  message: 'Content',
  theme: 'round-button',
}).then(() => {
  // on close
});

Async Close

const beforeClose = (action) =>
  new Promise((resolve) => {
    setTimeout(() => {
      resolve(action === 'confirm');
    }, 1000);
  });

Dialog.confirm({
  title: 'Title',
  message: 'Content',
  beforeClose,
});

Global Method

After registering the Dialog component through app.use, the $dialog method will be automatically mounted on all subComponents of the app.

export default {
  mounted() {
    this.$dialog.alert({
      message: 'Content',
    });
  },
};

Advanced Usage

If you need to render vue components within a dialog, you can use dialog component.

<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 };
  },
};

Methods

Name	Description	Attribute	Return value
Dialog	Show dialog	options: DialogOptions	`Promise<void>`
Dialog.alert	Show alert dialog	options: DialogOptions	`Promise<void>`
Dialog.confirm	Show confirm dialog	options: DialogOptions	`Promise<void>`
Dialog.setDefaultOptions	Set default options of all dialogs	options: DialogOptions	`void`
Dialog.resetDefaultOptions	Reset default options of all dialogs	-	`void`
Dialog.close	Close dialog	-	`void`

DialogOptions

Attribute	Description	Type	Default
title	Title	string	-
width	Dialog width	number \| string	`320px`
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 \| object	-
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`
confirmButtonDisabled `v3.5.0`	Whether to disable cancel button	boolean	`false`
confirmButtonText	Confirm button text	string	`Confirm`
confirmButtonColor	Confirm button color	string	`#ee0a24`
confirmButtonDisabled `v3.5.0`	Whether to disable confirm button	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`

Props

Attribute	Description	Type	Default
v-model:show	Whether to show dialog	boolean	-
title	Title	string	-
width	Width	number \| string	`320px`
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 `v3.5.0`	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 `v3.5.0`	Whether to disable confirm button	boolean	`false`
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	-

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 `v3.0.11`	Custom footer

Types

The component exports the following type definitions:

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

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-animation-duration-base)	-
--van-dialog-border-radius	16px	-
--van-dialog-background-color	var(--van-background-color-light)	-
--van-dialog-header-font-weight	var(--van-font-weight-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-danger-color)	-

Dialog