Van Dialog

Vant Dialog Component

A modal dialog component for message prompts, confirmations, or specific interactive operations. Supports both component and function call methods.

When to Invoke

Invoke this skill when:

• User needs to show alert messages to users
• User wants to implement confirmation dialogs
• User needs to display modal content with custom components
• User asks about async close operations
• User wants to implement form dialogs or custom modal content

Features

• Function Call: Quick invocation via showDialog and showConfirmDialog
• Component Call: Full customization via component usage
• Round Button Theme: Alternative rounded button style
• Async Close: Support async operations before closing
• Custom Content: Embed any content via slots
• Keyboard Support: Enter/Esc key bindings
• Teleport: Mount to specified element

API Reference

Methods

DialogOptions

Props (Component Usage)

Events

Slots

Usage Examples

Alert Dialog

<script setup>
import { showDialog } from 'vant'

const showAlert = () => {
  showDialog({
    title: 'Title',
    message: 'This is an alert message.'
  }).then(() => {
    console.log('Dialog closed')
  })
}
</script>

Confirm Dialog

<script setup>
import { showConfirmDialog } from 'vant'

const showConfirm = () => {
  showConfirmDialog({
    title: 'Confirm',
    message: 'Are you sure you want to proceed?'
  })
    .then(() => {
      console.log('Confirmed')
    })
    .catch(() => {
      console.log('Cancelled')
    })
}
</script>

Round Button Style

<script setup>
import { showDialog } from 'vant'

const showRoundDialog = () => {
  showDialog({
    title: 'Title',
    message: 'Round button style dialog',
    theme: 'round-button'
  })
}
</script>

Async Close

<script setup>
import { showConfirmDialog } from 'vant'

const showAsyncDialog = () => {
  showConfirmDialog({
    title: 'Async Close',
    message: 'Dialog will close after 1 second',
    beforeClose: (action) => {
      return new Promise((resolve) => {
        setTimeout(() => {
          resolve(action === 'confirm')
        }, 1000)
      })
    }
  })
}
</script>

Component Usage

<template>
  <van-dialog 
    v-model:show="show" 
    title="Title" 
    show-cancel-button
    @confirm="handleConfirm"
  >
    <img src="https://example.com/image.jpg" />
  </van-dialog>
</template>

<script setup>
import { ref } from 'vue'

const show = ref(false)

const handleConfirm = () => {
  console.log('Confirmed')
}
</script>

Custom Footer

<template>
  <van-dialog v-model:show="show" title="Custom Footer">
    <p>Custom content here</p>
    <template #footer>
      <van-button block @click="show = false">Close</van-button>
    </template>
  </van-dialog>
</template>

Common Issues

1. Dialog Not Closing on Overlay Click

By default, closeOnClickOverlay is false. Enable it if needed:

showDialog({
  message: 'Message',
  closeOnClickOverlay: true
})

2. HTML Content Not Rendering

Enable allowHtml for HTML content:

showDialog({
  message: '<strong>Bold text</strong>',
  allowHtml: true
})

3. Preventing Dialog Close

Use beforeClose to prevent closing:

showConfirmDialog({
  message: 'Message',
  beforeClose: (action) => {
    if (action === 'confirm') {
      return validateForm()
    }
    return true
  }
})

Component Interactions

With Form Validation

<script setup>
import { ref } from 'vue'
import { showConfirmDialog, showToast } from 'vant'

const form = ref({ name: '', email: '' })

const submitForm = async () => {
  if (!form.value.name) {
    showToast('Please enter name')
    return
  }
  
  try {
    await showConfirmDialog({
      title: 'Submit',
      message: 'Are you sure to submit?'
    })
    await submitToServer(form.value)
    showToast('Success')
  } catch {
    console.log('Cancelled')
  }
}
</script>

With Loading State

<script setup>
import { showConfirmDialog, closeDialog } from 'vant'

const saveWithLoading = () => {
  showConfirmDialog({
    title: 'Saving...',
    message: 'Please wait',
    showCancelButton: false,
    closeOnClickOverlay: false,
    beforeClose: async () => {
      await saveData()
      return true
    }
  })
}
</script>

Best Practices

1. Clear messages: Keep dialog messages concise and clear
2. Action labels: Use descriptive button text (e.g., "Delete" instead of "Confirm")
3. Destructive actions: Use confirmation dialogs for destructive operations
4. Async operations: Use beforeClose for async validation
5. Accessibility: Provide meaningful titles for screen readers
6. Default options: Use setDialogDefaultOptions for consistent styling