dialog

Displays messages to your users in flexible and promised dialogs

It is a simple and easy-to-use plugin that allows you to display messages to your users in flexible and promised dialogs. The plugin will mount the MazDialogPromise component to the root of your application and provide you with a handler to open the dialog, close it and return a promise.

TIP

This plugin has a composable for easier use, after installing it you can use useDialog

Basic usage

You can display a simple dialog with a title and a message. The dialog will have a confirm and a cancel button. The confirm button will resolve the promise and the cancel button will reject it.

<template>
  <MazBtn color="theme" @click="openDialog">
    Show dialog
  </MazBtn>
</template>

<script lang="ts" setup>
  import { useDialog, useToast } from 'maz-ui'

  const dialog = useDialog()
  const toast = useToast()

  async function openDialog() {
    const { promise } = dialog.open({
      title: 'Dialog title',
      message: 'Dialog message',
    })

    try {
      await promise

      toast.success('Dialog confirmed', {
        position: 'bottom',
      })
    } catch (error) {
      toast.error('Dialog cancelled', {
        position: 'bottom',
      })
    }
  }
</script>

Custom buttons with actions

The buttons property allows you to display custom buttons in the dialog and replace the default confirm and cancel buttons. You can use all props of MazBtn component. Each button can have a custom action to execute when clicked.

<template>
  <MazBtn color="theme" @click="openDialogActions">
    Show dialog with custom buttons
  </MazBtn>
</template>

<script lang="ts" setup>
  import { useDialog, useToast } from 'maz-ui'

  const dialog = useDialog()
  const toast = useToast()

  async function openDialogActions() {
    dialog.open({
      title: 'Dialog title',
      message: 'Dialog message',
      buttons: [
        {
          text: 'Custom button',
          color: 'info',
          action: () => {
            toast.info('Custom button clicked', {
              position: 'bottom',
            })
          },
        },
        {
          text: 'Custom button 2',
          color: 'success',
          action: () => {
            toast.success('Custom button 2 clicked', {
              position: 'bottom',
            })
          },
        }
      ],
    })
  }
</script>

Custom promised buttons

The buttons property allows you to display custom buttons in the dialog and replace the default confirm and cancel buttons. Each button can have a custom action to execute when clicked. The type property allows you to define the type of the button. The response property allows you to define the response of the promise when the button is clicked.

<template>
  <MazBtn color="theme" @click="openDialogPromised">
    Show dialog with custom promised buttons
  </MazBtn>
</template>

<script lang="ts" setup>
  import { useDialog, useToast } from 'maz-ui'

  const dialog = useDialog()
  const toast = useToast()

  async function openDialogPromised() {
    const { promise } = dialog.open({
      title: 'Dialog title',
      message: 'Dialog message',
      buttons: [
        {
          text: 'Reject',
          type: 'reject',
          response: 'Rejected Response',
          color: 'danger',
        },
        {
          text: 'Accept',
          type: 'resolve',
          response: 'Accepted Response',
          color: 'success',
        }
      ],
    })

    try {
      const reponse = await promise

      toast.success(`Dialog resolved with: ${reponse}`, {
        position: 'bottom',
      })
    } catch (error) {
      toast.error(`Dialog rejected with: ${error}`, {
        position: 'bottom',
    })
  }
}
</script>

Close dialog

You can close the dialog programmatically by calling the close method returned by the open method.

<template>
  <MazBtn color="theme" @click="openAndCloseDialog">
    Open and close dialog
  </MazBtn>
</template>

<script lang="ts" setup>
  import { useDialog, useToast } from 'maz-ui'

  const dialog = useDialog()

  async function openAndCloseDialog() {
    const { close } = dialog.open({
      title: 'Dialog title',
      message: 'Wait 5 seconds to close the dialog',
      buttons: [],
      persistent: true,
    })

    setTimeout(() => {
      close()
    }, 5000);
  }
</script>

Install

main.ts or main.js

import { createApp } from 'vue'
import { installDialog, DialogOptions } from 'maz-ui'

const app = createApp(App)

const dialogOptions: DialogOptions = {
  ...
}

app.use(installDialog, dialogOptions)

app.mount('#app')

Options

Usage

import { injectStrict, type DialogHandler } from 'maz-ui'

const dialog = injectStrict<DialogHandler>('dialog')
/*
 * or use `useDialog` composable to get the dialog handler
 * const dialog = useDialog()
 */

const options: DialogOptions = {
  title: 'Dialog title',
  message: 'Dialog message',
}

dialog.open(options)

Type

import type { Props as MazBtnProps } from 'maz-ui/components/MazBtn'

type DialogOptions = Partial<Omit<MazDialogPromiseProps, 'modelValue'>> & {
  /**
   * Dialog identifier - identifier to manage multiple dialogs
   * @default 'main-dialog'
   */
  identifier?: string
  /** Is callback function to execute when the dialog is resolved */
  promiseCallback?: () => unknown
  /**
   * Custom buttons to display in the dialog and replace the default confirm and cancel buttons
   * @type {DialogCustomButton[]}
   */
  buttons?: DialogCustomButton[]
  /** Confirm button props and data */
  confirmButton: {
    /**
     * Replace the confirm button text
     * @default 'Confirm'
     */
    text?: string
  } & MazBtnProps,
  /** Cancel button props and data */
  cancelButton: {
    /**
     * Replace the cancel button text
     * @default 'Cancel'
     */
    text?: string
  } & MazBtnProps,
}