Vue Final Modal

Common errors

• The requested module 'vue-final-modal' does not provide an export named 'VueFinalModal'

  cause Attempting to import `VueFinalModal` as a default export or using an incorrect named import.
  fix Change your import statement to `import { VueFinalModal } from 'vue-final-modal'`.

• Cannot read properties of undefined (reading 'open') when using useModal

  cause `ModalsContainer` component is not present in the application's template.
  fix Add `<ModalsContainer />` to your root `App.vue` or parent layout component where programmatic modals should render.

• Property 'modalId' does not exist on type 'VfmModal'

  cause Attempting to access properties like `modalId` on the `useModal` instance directly when it might not be immediately available or typed correctly in all contexts.
  fix Access properties like `modalId` from the modal instance returned by `open()` or ensure correct type inference for dynamically created modals, especially if you're passing custom props.

Warnings

• breaking Migration from v3 to v4 involved significant API changes. Direct upgrades without consulting the migration guide will likely result in breaking applications.
  Fix: Refer to the official migration guide from v3 to v4: https://v4.vue-final-modal.org/get-started/migration/from-v3
• breaking Version 5.0.0 (currently in beta) replaces `body-scroll-lock` with `scroll-lock` as a dependency. While this might be a minor change for most users, direct usage or assumptions about the underlying scroll-lock mechanism might require updates.
  Fix: Review your `scroll-lock` related configurations if you directly interacted with `body-scroll-lock` in previous versions. Check the v5 beta release notes for details.
• gotcha When using `useModal` for programmatic modals, the `ModalsContainer` component *must* be mounted somewhere in your application. Without it, programmatic modals will not render.
  Fix: Add `<ModalsContainer />` to your `App.vue` or a main layout component.
• gotcha Ensure proper focus management and keyboard accessibility. While `vue-final-modal` integrates `focus-trap`, custom content within modals might interfere or require additional `aria` attributes for screen readers.
  Fix: Test modal interactions thoroughly with keyboard navigation and screen readers. Add appropriate ARIA roles and labels to custom modal content and controls.
• gotcha Incorrectly applying CSS transitions or animations can lead to unexpected visual glitches or modals not appearing/disappearing smoothly. Ensure your transition classes are correctly configured.
  Fix: Verify that `overlay-transition` and `content-transition` props correctly map to your CSS transition classes. Use browser developer tools to inspect applied classes during modal transitions.

Install

• npm install vue-final-modal npm
• yarn add vue-final-modal yarn
• pnpm add vue-final-modal pnpm

Imports

• VueFinalModal
  wrong:

  import VueFinalModal from 'vue-final-modal'

  correct:

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

  This is a named export, not a default export. Ensure you destructure it correctly.
• useModal
  wrong:

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

  correct:

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

  The primary composable for programmatic modal control. It's a named export and typically lowercase `useModal` following Vue composable conventions.
• ModalsContainer

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

  Required to render modals managed by `useModal`. This component should be placed once at the root of your app or layout.

Quickstart

This quickstart demonstrates two ways to use Vue Final Modal: declarative with v-model and programmatically using the `useModal` composable. It shows basic modal opening/closing and integrates the `ModalsContainer` for programmatic modals.

import { createApp, ref } from 'vue'
import { VueFinalModal, useModal, ModalsContainer } from 'vue-final-modal'

const app = createApp({
  template: `
    <button @click="openModal">Open Modal</button>
    <VueFinalModal
      v-model="showModal"
      classes="flex justify-center items-center"
      content-class="relative flex flex-col max-h-full mx-4 p-4 border dark:border-gray-800 rounded bg-white dark:bg-gray-900"
      :overlay-transition="'vfm-fade'"
      :content-transition="'vfm-slide-up'"
      @before-close="beforeClose"
    >
      <h1 class="text-xl">Hello, Vue Final Modal!</h1>
      <p>This is a custom modal opened via a ref.</p>
      <button class="mt-4 p-2 bg-blue-500 text-white rounded" @click="showModal = false">Close</button>
    </VueFinalModal>
    <button @click="openProgrammaticModal">Open Programmatic Modal</button>
    <ModalsContainer />
  `,
  setup() {
    const showModal = ref(false)
    const { open, close } = useModal({
      component: VueFinalModal,
      attrs: {
        title: 'Programmatic Modal',
        onUpdateModelValue: (val) => console.log('Programmatic modal v-model:', val)
      },
      slots: {
        default: '<p>This modal was opened programmatically!</p><button @click="options.close">Close</button>'
      }
    })

    function openModal() {
      showModal.value = true
    }

    function beforeClose() {
      console.log('Modal is about to close')
      // You can prevent closing here if needed
      // return false
    }

    function openProgrammaticModal() {
      open()
    }

    return { showModal, openModal, beforeClose, openProgrammaticModal }
  }
})

app.component('VueFinalModal', VueFinalModal)
app.mount('#app')