Vue-material-modal-dialog NPM

A reusable modal dialog for Vue Material

Minified size Open issues Total downloads License

In Vue Material, components showing a dialog have to contain an MdDialog, or a component based on MdDialog. This couples the modal dialog to the surrounding component and creates a separate dialog instance/comment placeholder for each occurrence, eventually multiplied by v-for.

This repository provides a component, MdModalDialog, that avoids this situation. It acts as a substitute for Vue Material's MdDialog, offering the following additional features:

MdModalDialogs are completely decoupled from other components
They only have to be imported but not to be placed in the <template> of other components
MdModalDialog supports the same props and events as MdDialog
You can show MdModalDialogs from anywhere in your app (e.g. from a Vuex action), not only from component methods
Simple API: showing the dialog returns a promise which will be fulfilled or rejected when the dialog is closed
Input data can be transferred from the dialog to the calling component
Properties can be passed for runtime customization of the dialog
At any point in time there will be at most one single MdModalDialog instance

A simple online example is available here (example source code).

Installation

As a module:

$ npm install vue-material-modal-dialog
    or
$ yarn add vue-material-modal-dialog

Included as <script>:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vue-material-modal-dialog/dist/components.css">
<script src="https://cdn.jsdelivr.net/npm/vue-material-modal-dialog/dist/components.min.js"></script>

Usage

Registering the `MdModalDialog` component

import MdModalDialog from 'vue-material-modal-dialog'
import 'vue-material-modal-dialog/dist/md-modal-dialog.css'
    ...
// This must come after Vue.use(VueMaterial):
Vue.use(MdModalDialog)

Controlling modal dialogs

MdModalDialog provides these functions:

`vm.$modal.show(dialog, [props])`, `Vue.$modal.show(dialog, [props])`

{Vue component} dialog
{Object} [props]

Shows a dialog component in pristine state, can pass props to the dialog instance; does not preserve the dialog state across show() calls.

Returns a Promise that can be fulfilled by vm.$modal.submit() and rejected by vm.$modal.cancel(). Either function closes the dialog.

`vm.$modal.submit([result])`, `Vue.$modal.submit([result])`

{Any} [result]

Closes the dialog and fulfills the Promise; can return a result.

`vm.$modal.cancel([reason])`, `Vue.$modal.cancel([reason])`

{Any} [reason]

Closes the dialog and rejects the Promise; can return a reason for rejection.

Creating modal dialog components

Just use MdModalDialog in the same way as you would use MdDialog (without md-active), for example for an input dialog:

<template>
  <md-modal-dialog>
    <md-dialog-title>Guess a number</md-dialog-title>

    <md-dialog-content>
      <md-field>
        <label>A number</label>
        <md-input type="number" v-model="number" />
      </md-field>
    </md-dialog-content>

    <md-dialog-actions>
      <md-button @click="$modal.submit(number)">Submit</md-button>
      <md-button @click="$modal.cancel()">Cancel</md-button>  
    </md-dialog-actions>
  </md-modal-dialog>
</template>

<script>
  export default {
    name: 'GuessDialog',
      ...
  }
</script>

Showing GuessDialog and receiving the guessed number in some other component:

vm.$modal
    .show(GuessDialog)
    .then(number => {
        // Do something with "number"
    })
    .catch(reason => {
        // In order to avoid runtime warnings, a catch clause
        // is required even if "reason" is ignored
    })      
}

Passing properties to modal dialogs

Since MdModalDialogs are not placed like regular components, no props can be passed to them. However, using v-slot, we can pass properties to such a dialog every time it is shown.

Let us extend the example with a configurable upper limit max for the guessed number:

<template>
  <md-modal-dialog v-slot="{ max }">
    <md-dialog-title>Guess a number up to {{ max }}</md-dialog-title>

    <md-dialog-content>
      <md-field>
        <label>A number</label>
        <md-input type="number" v-model="number" :max="max" />
      </md-field>
    </md-dialog-content>
    ...
</template>
...

Showing GuessDialog and passing a max value:

vm.$modal
    .show(GuessDialog, { max: 42 })
    .then(...)
    .catch(...)

In the methods of the modal dialog component, such properties can be accessed through the object vm.$modal.slotProps.

Returning a reason on `ESC` and outside clicks

If a dialog is configured to be closed by clicking outside and/or by ESC,
and if a reason is to be returned in these cases

then this is one possible approach:

<template>
  <md-modal-dialog
    @md-clicked-outside="$modal.cancel('byClick')"
    @keydown.esc="$modal.cancel('byEsc')">
      ...
    <md-button @click="$modal.cancel('byButton')">Cancel</md-button>
      ...
  </md-modal-dialog>
</template>