Registry / web-framework / vue-final-modal

vue-final-modal

JSON →
library4.5.5jsnpmunverified

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.

npm install vue-final-modal
INSTALL
IMPORT
SIG · VUE-FINAL-MODAL
V
vue-final-modal
web-frameworkjavascriptv4.5.5
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

VueFinalModal
import { VueFinalModal } from 'vue-final-modal'
import VueFinalModal from 'vue-final-modal'
This is a named export, not a default export. Ensure you destructure it correctly.
useModal
import { useModal } from 'vue-final-modal'
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.

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')
Debug
Known issues
breakingMigration 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
affects: ^4.0.0
breakingVersion 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.
affects: >=5.0.0-beta.0
gotchaWhen 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.
affects: >=4.0.0
gotchaEnsure 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.
affects: >=4.0.0
gotchaIncorrectly 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.
affects: >=4.0.0
Errors
Common errors & fixes
The requested module 'vue-final-modal' does not provide an export named 'VueFinalModal'
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
`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'
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.
Upgrade
Version history
4.5.5latest on npm
Audit
Dependencies
@vueuse/corerequiredUtility functions and composables used internally for reactivity, state management, and DOM interactions.
@vueuse/integrationsrequiredProvides integrations with other libraries, potentially for features like focus management or animation helpers.
focus-traprequiredCrucial for accessibility, ensuring keyboard focus is contained within the modal when it's open.
vuerequiredThe core framework dependency for any Vue 3 library.
Agent activity
5 hits · last 30 days
node
4
OpenAI (training)
1
Resources