{"id":12474,"library":"vue-final-modal","title":"Vue Final Modal","description":"Vue Final Modal is a highly optimized and lightweight modal library specifically designed for Vue 3 applications, providing robust dialog, popup, and overlay functionalities. The current stable version is 4.5.5, with an active beta development for version 5.0.0, indicating a consistent release cadence with a focus on ongoing improvements and new features. Key differentiators include its balance of power and lightweight footprint, extensive customization options, and strong TypeScript support, making it suitable for complex UIs while maintaining performance. It handles common modal concerns like accessibility, scroll locking, and stacking contexts effectively, providing a comprehensive solution for interactive overlays in Vue 3 projects.","status":"active","version":"4.5.5","language":"javascript","source_language":"en","source_url":"https://github.com/vue-final/vue-final-modal","tags":["javascript","vue","modal","dialog","popup","typescript"],"install":[{"cmd":"npm install vue-final-modal","lang":"bash","label":"npm"},{"cmd":"yarn add vue-final-modal","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-final-modal","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Utility functions and composables used internally for reactivity, state management, and DOM interactions.","package":"@vueuse/core","optional":false},{"reason":"Provides integrations with other libraries, potentially for features like focus management or animation helpers.","package":"@vueuse/integrations","optional":false},{"reason":"Crucial for accessibility, ensuring keyboard focus is contained within the modal when it's open.","package":"focus-trap","optional":false},{"reason":"The core framework dependency for any Vue 3 library.","package":"vue","optional":false}],"imports":[{"note":"This is a named export, not a default export. Ensure you destructure it correctly.","wrong":"import VueFinalModal from 'vue-final-modal'","symbol":"VueFinalModal","correct":"import { VueFinalModal } from 'vue-final-modal'"},{"note":"The primary composable for programmatic modal control. It's a named export and typically lowercase `useModal` following Vue composable conventions.","wrong":"import { UseModal } from 'vue-final-modal'","symbol":"useModal","correct":"import { useModal } from 'vue-final-modal'"},{"note":"Required to render modals managed by `useModal`. This component should be placed once at the root of your app or layout.","symbol":"ModalsContainer","correct":"import { ModalsContainer } from 'vue-final-modal'"}],"quickstart":{"code":"import { createApp, ref } from 'vue'\nimport { VueFinalModal, useModal, ModalsContainer } from 'vue-final-modal'\n\nconst app = createApp({\n  template: `\n    <button @click=\"openModal\">Open Modal</button>\n    <VueFinalModal\n      v-model=\"showModal\"\n      classes=\"flex justify-center items-center\"\n      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\"\n      :overlay-transition=\"'vfm-fade'\"\n      :content-transition=\"'vfm-slide-up'\"\n      @before-close=\"beforeClose\"\n    >\n      <h1 class=\"text-xl\">Hello, Vue Final Modal!</h1>\n      <p>This is a custom modal opened via a ref.</p>\n      <button class=\"mt-4 p-2 bg-blue-500 text-white rounded\" @click=\"showModal = false\">Close</button>\n    </VueFinalModal>\n    <button @click=\"openProgrammaticModal\">Open Programmatic Modal</button>\n    <ModalsContainer />\n  `,\n  setup() {\n    const showModal = ref(false)\n    const { open, close } = useModal({\n      component: VueFinalModal,\n      attrs: {\n        title: 'Programmatic Modal',\n        onUpdateModelValue: (val) => console.log('Programmatic modal v-model:', val)\n      },\n      slots: {\n        default: '<p>This modal was opened programmatically!</p><button @click=\"options.close\">Close</button>'\n      }\n    })\n\n    function openModal() {\n      showModal.value = true\n    }\n\n    function beforeClose() {\n      console.log('Modal is about to close')\n      // You can prevent closing here if needed\n      // return false\n    }\n\n    function openProgrammaticModal() {\n      open()\n    }\n\n    return { showModal, openModal, beforeClose, openProgrammaticModal }\n  }\n})\n\napp.component('VueFinalModal', VueFinalModal)\napp.mount('#app')\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Refer to the official migration guide from v3 to v4: https://v4.vue-final-modal.org/get-started/migration/from-v3","message":"Migration from v3 to v4 involved significant API changes. Direct upgrades without consulting the migration guide will likely result in breaking applications.","severity":"breaking","affected_versions":"^4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0-beta.0"},{"fix":"Add `<ModalsContainer />` to your `App.vue` or a main layout component.","message":"When using `useModal` for programmatic modals, the `ModalsContainer` component *must* be mounted somewhere in your application. Without it, programmatic modals will not render.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Test modal interactions thoroughly with keyboard navigation and screen readers. Add appropriate ARIA roles and labels to custom modal content and controls.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import { VueFinalModal } from 'vue-final-modal'`.","cause":"Attempting to import `VueFinalModal` as a default export or using an incorrect named import.","error":"The requested module 'vue-final-modal' does not provide an export named 'VueFinalModal'"},{"fix":"Add `<ModalsContainer />` to your root `App.vue` or parent layout component where programmatic modals should render.","cause":"`ModalsContainer` component is not present in the application's template.","error":"Cannot read properties of undefined (reading 'open') when using useModal"},{"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.","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.","error":"Property 'modalId' does not exist on type 'VfmModal'"}],"ecosystem":"npm"}