Migration Guide

This document should help you navigate the tricky path of migrating between different versions of vue-final-modal that introduced breaking changes:

Migrating from 3.x to 4.0

vue-final-modal 4.0 introduced a lot of breaking changes.

You should treat 4.x as a different library and read the documentation carefully, however these are some pointers towards more of the significant changes.

To migrate from 3.x you need to understand some of the changes to the public API and note that there is not direct path to upgrade and if you have a large app and you don't need some of the newer features, consider staying at the 3.x releases.

Step by step

Removed vfmPlugin

In Vue 3

So this:

import { vfmPlugin } from 'vue-final-modal'

app.use(vfmPlugin)

Will be re-written as this:

import { createVfm } from 'vue-final-modal'
const vfm = createVfm()
app.use(vfm)

In Nuxt 3

So this:

import { defineNuxtPlugin } from '#imports'
import { vfmPlugin } from 'vue-final-modal'

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.vueApp.use(vfmPlugin)
})

Will be re-written as this:

import { createVfm } from 'vue-final-modal'

export default defineNuxtPlugin((nuxtApp) => {
  const vfm = createVfm() as any

  nuxtApp.vueApp.use(vfm)
})

Import Required CSS

In Vue 3

import 'vue-final-modal/style.css'

In Nuxt 3

export default defineNuxtConfig({
  css: ['vue-final-modal/style.css'],
})

Removed Dynamic Modal $vfm.show

If you are using $vfm.show() to create dynamic modals. You have to re-written them with useModal() composable.

So this:

this.$vfm.show({
  component: ModalConfirm,
  bind: {
    name: 'ModalConfirmName'
  },
  on: {
    confirm() {
      this.$vfm.hide('ModalConfirmName')
    },
    opened() {
      console.log('modal opened')
    },
  },
  slots: {
    default: '<p>The content of the modal</p>'
  }
})

Will be re-written as this:

const { open, close } = useModal({
  component: ModalConfirm,
  attrs: {
    title: 'Hello World!',
    onConfirm() {
      close()
    },
    onOpened() {
      console.log('modal opened')
    }
  },
  slots: {
    default: '<p>The content of the modal</p>',
  },
})
open()

Removed params

params is not a good practice and hard to keep type-save in Typescript. So if you are using params, you have to re-written it with useModal() composable.

Delete Drag & Resize

To keep vue-final-modal simple and easier to maintain, I decided to remove the Drag & Resize feature.

If you are using Drag & Resize, please consider staying at the 3.x releases.

Here is a new drag & resize example with an awesome library vue3-drag-resize:

Renamed properties

Deleted properties

Renamed APIs $vfm to useVfm

• You can still use this.$vfm in Options API.
• If you are using script setup syntax:

  import { $vfm } from 'vue-final-modal'
  
  $vfm.show(...)
  $vfm.hide(...)
  $vfm.hideAll(...)
  

  Copy to clipboard
  
  Will be re-written as this:

  import { useVfm } from 'vue-final-modal'
  
  const vfm = useVfm()
  
  vfm.open(...)
  vfm.close(...)
  vfm.closeAll(...)
  

  Copy to clipboard