N Dialog

Naive UI Dialog Component

Dialog component for modal confirmations, alerts, and user interactions requiring attention.

When to Use

Use this component when:

• Confirmations: Ask users to confirm destructive or important actions
• Alerts: Display important information that requires user acknowledgment
• Form dialogs: Collect user input in a modal context
• Async operations: Handle operations that require user confirmation before proceeding

When to Invoke

Invoke this skill when:

• User needs to create confirmation dialogs
• User wants to use imperative API with useDialog
• User needs async dialog operations
• User wants to customize dialog content and actions
• User asks about dialog provider setup

Features

• Imperative API: Create dialogs programmatically with useDialog
• Multiple Types: info, success, warning, error
• Async Support: Handle async operations with loading states
• Customizable Actions: Custom action buttons and content
• Draggable: Optional drag functionality
• Mask Control: Configurable mask click behavior
• Keyboard Support: ESC key to close
• Component Mode: Use as a declarative component

API Reference

useDialog API

useDialogReactiveList API

() => Ref<readonly DialogReactive[]>

DialogOptions Properties

DialogReactive Methods

Dialog Props (Component Mode)

Dialog Slots

Basic Usage

Setup with DialogProvider

<!-- App.vue -->
<template>
  <n-dialog-provider>
    <Content />
  </n-dialog-provider>
</template>

Basic Dialog Types

<template>
  <n-space>
    <n-button @click="handleConfirm">Confirm</n-button>
    <n-button @click="handleSuccess">Success</n-button>
    <n-button @click="handleError">Error</n-button>
  </n-space>
</template>

<script setup>
import { useDialog } from 'naive-ui'

const dialog = useDialog()

const handleConfirm = () => {
  dialog.warning({
    title: 'Confirm',
    content: 'Are you sure you want to proceed?',
    positiveText: 'Confirm',
    negativeText: 'Cancel',
    onPositiveClick: () => {
      console.log('Confirmed')
    }
  })
}

const handleSuccess = () => {
  dialog.success({
    title: 'Success',
    content: 'Operation completed successfully',
    positiveText: 'OK'
  })
}

const handleError = () => {
  dialog.error({
    title: 'Error',
    content: 'Something went wrong',
    positiveText: 'OK'
  })
}
</script>

Async Dialog

<template>
  <n-button @click="handleAsync">Async Operation</n-button>
</template>

<script setup>
import { useDialog } from 'naive-ui'

const dialog = useDialog()

const handleAsync = () => {
  const d = dialog.warning({
    title: 'Async Operation',
    content: 'Processing...',
    positiveText: 'Submit',
    loading: true,
    onPositiveClick: async () => {
      try {
        await new Promise(resolve => setTimeout(resolve, 2000))
        d.loading = false
        return true
      } catch {
        d.loading = false
        return false
      }
    }
  })
}
</script>

Component Mode

<template>
  <n-dialog
    v-model:show="show"
    title="Dialog"
    content="Are you sure?"
    negative-text="Cancel"
    positive-text="Submit"
    @positive-click="handlePositiveClick"
    @negative-click="handleNegativeClick"
  />
</template>

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

const show = ref(false)

const handlePositiveClick = () => {
  console.log('Positive clicked')
}

const handleNegativeClick = () => {
  console.log('Negative clicked')
}
</script>

Custom Actions

<template>
  <n-button @click="showCustomDialog">Custom Actions</n-button>
</template>

<script setup>
import { h } from 'vue'
import { useDialog, NButton } from 'naive-ui'

const dialog = useDialog()

const showCustomDialog = () => {
  dialog.warning({
    title: 'Custom Actions',
    content: 'Dialog with custom action buttons',
    action: () => [
      h(NButton, { onClick: () => dialog.destroyAll() }, () => 'Close All'),
      h(NButton, { type: 'primary', onClick: () => console.log('Custom') }, () => 'Custom')
    ]
  })
}
</script>

Mask Click Callback

<template>
  <n-button @click="showDialog">Mask Click Callback</n-button>
</template>

<script setup>
import { useDialog, useMessage } from 'naive-ui'

const dialog = useDialog()
const message = useMessage()

const showDialog = () => {
  dialog.warning({
    title: 'Click Mask',
    content: 'Try clicking the mask',
    maskClosable: true,
    onMaskClick: () => {
      message.info('Mask clicked')
    }
  })
}
</script>

Draggable Dialog

<template>
  <n-button @click="showDraggable">Draggable Dialog</n-button>
</template>

<script setup>
import { useDialog } from 'naive-ui'

const dialog = useDialog()

const showDraggable = () => {
  dialog.warning({
    title: 'Draggable',
    content: 'This dialog can be dragged',
    draggable: true
  })
}
</script>

Common Patterns

Delete Confirmation

<template>
  <n-button type="error" @click="handleDelete">Delete Item</n-button>
</template>

<script setup>
import { useDialog } from 'naive-ui'

const dialog = useDialog()

const handleDelete = () => {
  dialog.error({
    title: 'Delete Confirmation',
    content: 'This action cannot be undone. Are you sure you want to delete this item?',
    positiveText: 'Delete',
    negativeText: 'Cancel',
    onPositiveClick: () => {
      // Perform delete operation
      console.log('Item deleted')
    }
  })
}
</script>

Form in Dialog

<template>
  <n-button @click="showFormDialog">Open Form</n-button>
</template>

<script setup>
import { h, ref } from 'vue'
import { useDialog, NInput, NSpace } from 'naive-ui'

const dialog = useDialog()
const inputValue = ref('')

const showFormDialog = () => {
  const d = dialog.warning({
    title: 'Enter Name',
    content: () => h(NInput, {
      value: inputValue.value,
      onUpdateValue: (v) => { inputValue.value = v }
    }),
    positiveText: 'Submit',
    negativeText: 'Cancel',
    onPositiveClick: () => {
      console.log('Submitted:', inputValue.value)
    }
  })
}
</script>

Access All Dialog Instances

<template>
  There is {{ dialogReactiveList.length }} dialog(s) on the current page.
</template>

<script setup>
import { useDialogReactiveList } from 'naive-ui'

const dialogReactiveList = useDialogReactiveList()
</script>

Best Practices

1. Wrap with DialogProvider: Always use n-dialog-provider at app root

   <n-dialog-provider>
     <App />
   </n-dialog-provider>
   

2. Use appropriate types: Match dialog type to message severity

   • warning for confirmations
   • error for error states
   • success for success messages
   • info for information

3. Handle async operations properly: Use loading state and return promises

   onPositiveClick: async () => {
     d.loading = true
     await someAsyncOperation()
     return true // close dialog
   }
   

4. Provide clear action labels: Use descriptive positive/negative text

5. Consider keyboard accessibility: Users can close with ESC by default

6. Destroy all dialogs when needed: Use destroyAll for cleanup

   dialog.destroyAll()