Vue Final Modal

Looking for a Vue 3 version? It's over here

🎉 Documentation

🙌 Examples

Introduction

Vue Final Modal is a renderless component!

You can create a higher-order component easily and can customize template, script and style based on your needs.

features:

• Support Vue 3 and Vue 2
• Tailwind CSS friendly
• Renderless component
• SSR support
• Stackable
• Detachable
• Scrollable
• Transition support
• Mobile friendly
• Tiny bundle size
• Accessibility support

Installation

Vue 3.0

NPM:

npm install vue-final-modal@next --save

Yarn:

yarn add vue-final-modal@next

Vue 2.0

NPM:

npm install vue-final-modal --save

Yarn:

yarn add vue-final-modal

Registeration

Vue

import VueFinalModal from 'vue-final-modal'

Vue.use(VueFinalModal())

Nuxt

• Write a plugin vue-final-modal.js

// plugins/vue-final-modal.js
import VueFinalModal from 'vue-final-modal/lib'

Vue.use(VueFinalModal())

• Add plugin into nuxt.config.js

// nuxt.config.js
export default {
  plugins: [
    { src: '~plugins/vue-final-modal.js' }
  ],
  build: {
    transpile: ['vue-final-modal']
  }
}

CDN

Live demo

• jsDelivr

<script src="https://cdn.jsdelivr.net/npm/vue-final-modal"></script>

• Unpkg

<script src="https://unpkg.com/vue-final-modal"></script>

Basic usage

Click button to open modal

<vue-final-modal v-model="showModal">
  Modal Content Here
</vue-final-modal>

<button @click="showModal = true">Launch</button>

Open modal with API

<vue-final-modal v-model="showModal" name="example">
  Modal Content Here
</vue-final-modal>

this.$vfm.show('example')

Configuration

Only work in v0.18+

Configuration options can be passed as a second argument to Vue.use.

import VueFinalModal from 'vue-final-modal'

Vue.use(VueFinalModal(), { ... })

componentName

• Type: String
• default: 'VueFinalModal'

Changes component name from "VueFinalModal" to any other string value. It is useful when there is already a global "modal" component.

key

• Type: String
• default: '$vfm'

Changes API name from "$vfm" to any other string value. It is useful when you use vue-final-modal as spinner, toast, notify, etc.

API

Plugin API can be called within any component through this.$vfm.

$vfm.openedModals

• Type: Array

A stack array store the opened modal's vue component instance.

You can use:

1. $vfm.openedModals[0] to get the first opened modal instance.
2. $vfm.openedModals.length to get how many modals is opened.

$vfm.modals

• Type: Array

All modal instances include show and hide.

$vfm.show(name)

• Type: Function
• Arguments:
  • name: String - Name of the modal
• Example:

<template>
    <vue-final-modal v-model="show" name="example">Vue Final Modal is awesome</vue-final-modal>
</template>

<script>
export default {
    name: 'MyComponent',
    data: () => ({
      show: false
    }),
    mounted () {
        this.$vfm.show('example')
    }
}
</script>

$vfm.hide(name)

• Type: Function
• Arguments:
  • name: String - Name of the modal
• Example:

<template>
    <vue-final-modal v-model="show" name="example">Vue Final Modal is awesome</vue-final-modal>
</template>

<script>
export default {
    name: 'MyComponent',
    data: () => ({
      show: true
    }),
    mounted () {
        this.$vfm.hide('example')
    }
}
</script>

$vfm.hideAll()

hide all modals.

$vfm.toggle(name, show)

• Type: Function
• Arguments:
  • name: String - Name of the modal
  • show: Boolean - Show modal or not

toggle modal by name.

Props

{
  value: { type: Boolean, default: false },
  ssr: { type: Boolean, default: true },
  classes: { type: [String, Object, Array], default: '' },
  overlayClass: { type: [String, Object, Array], default: '' },
  contentClass: { type: [String, Object, Array], default: '' },
  styles: { type: [String, Object, Array], default: '' },
  overlayStyle: { type: [String, Object, Array], default: '' },
  contentStyle: { type: [String, Object, Array], default: '' },
  lockScroll: { type: Boolean, default: true },
  hideOverlay: { type: Boolean, default: false },
  clickToClose: { type: Boolean, default: true },
  escToClose: { type: Boolean, default: false },
  preventClick: { type: Boolean, default: false },
  attach: { type: null, default: false, validator: validateAttachTarget },
  transition: { type: String, default: 'vfm' },
  overlayTransition: { type: String, default: 'vfm' },
  zIndexBase: { type: [String, Number], default: 1000 },
  zIndex: { type: [Boolean, String, Number], default: false },
  focusRetain: { type: Boolean, default: true },
  focusTrap: { type: Boolean, default: false }
}

Events

@click-outside

• Emits while modal container on click.

If prop clickToClose is false, the event will still be emitted.

@before-open

• Emits while modal is still invisible, but before transition starting.

@opened

• Emits after modal became visible and transition ended.

@before-close

• Emits before modal is going to be closed.

@closed

• Emits right before modal is destroyed.

Contribution

👋 Hi I'm Hunter, the author of vue-final-modal.

To develop vue-final-modal, I learn a lot from these awesome libraries:

• Vuetify
  • attach
• Element UI
  • stackable modal
  • zIndex
  • zIndexBase
• vue-js-modal
  • dynamic modal
  • transition
  • focusTrap for A11y
• Bootstrap Vue
  • lockScroll

There is no perfect library even the final of vue modal.

If you have any ideas for optimization of vue-final-modal, feel free to open issues or pull requests.