vuetify-dialog-promise

A Vue plugin with a Promise API for Vuetify dialogs and snackbar notifications.

Major and minor version history

• Version ^3.0.0: Vue 3 compatibility
• Version ^2.6.0: allows you to specify message.href in snackbars, linking to it when clicking on the text
• Version ^2.5.0: allows you to specify message.defaultValue in prompts, switches to v-card for snackbars, and updates dependencies
• Version ^2.4.0: switches to v-chip for snackbars because they're more suitable, and makes it possible to display multiple snackbars simultaneously.
• Version ^2.3.0: switches to v-btn for snackbars because a Vuetify update broke programmatic creation of non-absolute snackbars. Also removes the close button; now snackbars can be closed by clicking on them.
• Version ^2.2.0: no longer uses snackbarParent property (snackbars mounted in calling component instance)
• Version ^2.1.0: accepts theme property / config param (see Vuetify theme)
• Version ^2.0.0: requires Vuetify ^2.0.0
• Version ^1.0.0: requires Vuetify ^1.5.0

Description

Intended to be as straightforward to use as native browser dialogues, with the look and feel of Vuetify widgets and sufficient flexibility to cover most use cases involving straightforward alerts, notifications, confirmations, and prompts.

Adds the following methods to the Vue instance:

• $alert( message )
  • An alert dialog. Returns Promise, resolved when the user accepts it.
  • message can be a string, in which case it is displayed in a plain dialog with an "Accept" button, or an object with any properties including { text, title?, dialogMaxWidth?, acceptText?, cancelText? } where title becomes the dialog title, text becomes the message to display, and the other properties control the appearance and behaviour of the dialog (see "Configurable properties" below). Also applies to $confirm and $prompt (see below).
• $confirm( message )
  • A confirmation dialog. Returns Promise, resolved if the user accepts it, rejected if the user cancels it.
• $prompt( message )
  • A prompt dialog. Returns Promise, resolved with user input if user accepts it, rejected if the user cancels it.
  • An additional property message.defaultValue may be passed to the prompt
• $inform( message )
  • Raises a snackbar notification in the default colour.
  • message can be a string or an object with properties { text, color?, closeText?, snackbarX?, snackbarY?, snackbarTimeout? } where text becomes the message to display, and the other properties control the appearance and behaviour of the snackbar (see "Initialisation properties" below). Applies to $warn and $error also (see below).
• $warn( message )
  • Raises a snackbar notification in the warning colour.
• $error( message )
  • Raises a snackbar notification in the error colour.

Features

• Button labels localised to a large variety of languages (pull requests welcome)
• Allows you to inject your own button labels, overriding the defaults
• Dialogue and snackbar messages are plain text only: markup is escaped to keep it XSS-safe. However, paragraph breaks can be added with newline '\n' characters in the message.
• Various features of the dialogues and snackbars are configurable with initialisation properties (e.g. dialog max width, snackbar location, colour, duration)

Initialisation properties

Various properties can be configured by handing them to Vue.use in the options argument when installing the plugin. (see Usage examples below).

All of these are optional and have reasonable defaults:

• locale {string}
  • ISO locale identifier for the button labels. Over 30 locales are supported. To override, see the properties below.
• acceptText {string}
  • Label for accept button in dialog
• cancelText {string}
  • Label for cancel button in dialog
• closeText {string}
  • Label for close button in snackbar message
• snackbarX {"left"|"center"|"right"}
  • Position of snackbar message
• snackbarY {"top"|"bottom"}
  • Position of snackbar message
• snackbarTimeout {integer}
  • Snackbar duration in milliseconds
• dialogMaxWidth {integer}
  • Max width of dialog in pixels
• theme {Object}
  • Vuetify theme applied to dialogs

Usage examples

Directly in the browser

To experiment with the plugin directly in the browser, refer to this online example.

In a Vue CLI project

To install and configure (all init properties are optional, see "Initialisation properties" above for complete list):

import Vue from "vue";
import VuetifyDialogPromise from "vuetify-dialog-promise";

Vue.use( VuetifyDialogPromise, {
    locale : "fi",
    snackbarX : "left",
    snackbarY : "bottom"
} );

Inside your component after the plugin has been loaded

To use the plugin from inside your own component:

// Message with defaults
this.$alert( "Your mother is a hamster and your father smells of elderberries." );

// Confirmation with property overrides
this.$confirm( { 
    title : "Are you a witch?", 
    text : "Do you weigh less than a duck?", 
    acceptText : "I float", 
    cancelText : "I sink"
 } ).then( y => this.burnTheWitch() ).catch( n => this.notAWitch() );
 
// Prompt for value
this.$prompt( "What is your quest?" ).then( quest => 
    this.beginQuest( quest ).catch( n => {} );
    
// Snackbar notification with defaults    
this.$inform( "We are the knights that say Ni." );

// Snackbar notification with overrides
this.$inform( { text : "My favourite colour is blue.", color : "blue" } );

Developer notes

A full demo is provided with the project. To use it, fork and clone the repository and use the following utilities:

Project setup

npm install

Compiles and hot-reloads demo app for development

npm run serve

Compiles and minifies library for production

npm run build-bundle

Compiles and minifies demo app for production

npm run build

Run your tests

npm run test

Run your unit tests

npm run test:unit

Customize configuration

See Configuration Reference.

Credits

• Localisations for the standard button labels are originally extracted from the Dojo toolkit i18n.