---
title: "useMessageBox"
description: "Imperatively open alert and confirm dialogs and await the user's decision as a Promise."
canonical_url: "https://nuxt.mhaibaraai.cn/en/docs/composables/use-message-box"
---
# useMessageBox

> Imperatively open alert and confirm dialogs and await the user's decision as a Promise.

## Introduction

`useMessageBox` provides an imperative dialog API — pop up dialogs without declaring a component in the template. It is built on the [`MessageBox`](https://nuxt.mhaibaraai.cn/docs/components/message-box) component and Nuxt UI's `useOverlay`.

```ts
const { alert, confirm } = useMessageBox()
```

Both methods accept the props of `MessageBox` (`mode` is set automatically by the method): `title`, `description`, `type`, `icon`, button configuration, etc. See the component documentation for the full list.

## alert

`alert(options)` opens an alert box with only a confirm action. It returns a Promise that resolves after the user closes the dialog — suitable for blocking notifications:

```ts
const { alert } = useMessageBox()

async function onSave() {
  await save()
  await alert({ type: 'success', title: 'Saved successfully' })
  // Continues after the user closes the dialog
}
```

```vue [ComposablesUseMessageBoxAlertExample.vue]
<script setup lang="ts">
import type { SemanticColor } from '@movk/nuxt'

const props = defineProps<{
  type: SemanticColor
}>()

const { alert } = useMessageBox()
const log = ref<string[]>([])

async function showAlert() {
  await alert({
    type: props.type,
    title: `${props.type} alert`,
    description: '弹窗只暴露确认动作，关闭后 Promise 才会 resolve'
  })
  log.value = [`[${new Date().toLocaleTimeString()}] alert(${props.type}) closed`, ...log.value].slice(0, 6)
}
</script>

<template>
  <div class="flex flex-col gap-3">
    <UButton :color="type" variant="soft" size="sm" @click="showAlert">
      alert · {{ type }}
    </UButton>
    <p class="text-xs text-muted">
      <code>alert()</code> 返回 Promise；用户关闭弹窗后才会 resolve，可用于强同步的提示流程。
    </p>
    <pre class="text-xs bg-elevated/30 rounded p-3 overflow-auto max-h-40">{{ log }}</pre>
  </div>
</template>
```

## confirm

`confirm(options)` returns `Promise<boolean>`, mapping confirm/cancel to a boolean value:

```ts
const { confirm } = useMessageBox()

async function onDelete() {
  const ok = await confirm({
    type: 'warning',
    title: 'Confirm Delete',
    description: 'This action cannot be undone. Are you sure you want to continue?'
  })
  if (!ok) return
  await remove()
}
```

```vue [ComposablesUseMessageBoxConfirmExample.vue]
<script setup lang="ts">
import type { SemanticColor } from '@movk/nuxt'

const props = defineProps<{
  type: SemanticColor
}>()

const { confirm } = useMessageBox()
const log = ref<string[]>([])

async function showConfirm() {
  const ok = await confirm({
    type: props.type,
    title: `${props.type} confirm`,
    description: '弹窗返回确认结果，日志会记录 true / false'
  })
  log.value = [`[${new Date().toLocaleTimeString()}] confirm(${props.type}) → ${ok}`, ...log.value].slice(0, 6)
}
</script>

<template>
  <div class="flex flex-col gap-3">
    <UButton :color="type" variant="outline" size="sm" @click="showConfirm">
      confirm · {{ type }}
    </UButton>
    <p class="text-xs text-muted">
      <code>confirm()</code> 将确认或取消映射为 <code>boolean</code> 返回给调用方。
    </p>
    <pre class="text-xs bg-elevated/30 rounded p-3 overflow-auto max-h-40">{{ log }}</pre>
  </div>
</template>
```

## Async Confirmation Flow

`confirm` is well-suited for chaining async flows — execute the time-consuming task only after confirmation:

```vue [ComposablesUseMessageBoxAsyncExample.vue]
<script setup lang="ts">
const { confirm } = useMessageBox()
const log = ref<string[]>([])
const pending = ref(false)

async function showAsync() {
  const ok = await confirm({
    type: 'warning',
    title: '异步操作',
    description: '确认后再执行模拟耗时任务，日志在流程完成时更新',
    confirmButton: { label: '提交' }
  })
  if (!ok) {
    log.value = [`[${new Date().toLocaleTimeString()}] 已取消`, ...log.value].slice(0, 6)
    return
  }
  pending.value = true
  await new Promise(r => setTimeout(r, 1500))
  pending.value = false
  log.value = [`[${new Date().toLocaleTimeString()}] async confirm 完成`, ...log.value].slice(0, 6)
}
</script>

<template>
  <div class="flex flex-col gap-3">
    <UButton color="warning" icon="i-lucide-zap" :loading="pending" @click="showAsync">
      运行异步流程
    </UButton>
    <p class="text-xs text-muted">
      等待 <code>confirm()</code> 结果后再串行执行后续请求；命令式 API 让流程在脚本里线性表达。
    </p>
    <pre class="text-xs bg-elevated/30 rounded p-3 overflow-auto max-h-40">{{ log }}</pre>
  </div>
</template>
```

> [!TIP]
> See: /docs/components/message-box
> 
> See the MessageBox component documentation for declarative usage and the full props reference.


## Sitemap

See the full [sitemap](https://nuxt.mhaibaraai.cn/sitemap.md) for all pages.