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:

main.ts
import { vfmPlugin } from 'vue-final-modal'

app.use(vfmPlugin)

Will be re-written as this:

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

In Nuxt 3

So this:

./plugins/vue-final-modal.ts
import { defineNuxtPlugin } from '#imports'
import { vfmPlugin } from 'vue-final-modal'

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

Will be re-written as this:

./plugins/vue-final-modal.ts
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

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

In Nuxt 3

./nuxt.config.ts
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

3.x4.0Description
namemodalId-
ssrdisplay-directive-
attachteleportToUse <teleport> in Vue 3
preventClickbackground-
transitioncontentTransition-

Deleted properties

3.x4.0
classesJust use class
stylesJust use class
focusRetainMerged into focusTrap
zIndexAutoReplaced by zIndexFn
zIndexBaseReplaced by zIndexFn
zIndexReplaced by zIndexFn
dragNot support Drag & Resize anymore
fitParentNot support Drag & Resize anymore
dragSelectorNot support Drag & Resize anymore
keepChangedStyleNot support Drag & Resize anymore
resizeNot support Drag & Resize anymore
resizeDirectionsNot support Drag & Resize anymore
minWidthNot support Drag & Resize anymore
minHeightNot support Drag & Resize anymore
maxWidthNot support Drag & Resize anymore
maxHeightNot support Drag & Resize anymore

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(...)
    

    Will be re-written as this:
    import { useVfm } from 'vue-final-modal'
    
    const vfm = useVfm()
    
    vfm.open(...)
    vfm.close(...)
    vfm.closeAll(...)
    
3.x4.0
$vfm.show()vfm.open()
$vfm.hide()vfm.close()
$vfm.hideAll()vfm.closeAll()