{"id":12617,"library":"vue-universal-modal","title":"Vue Universal Modal","description":"Vue Universal Modal is a lightweight and simple modal plugin specifically designed for Vue 3 applications, leveraging Vue's built-in `teleport` feature. Currently at version 1.1.4, its release cadence appears to be relatively infrequent, with updates primarily focusing on bug fixes and dependency bumps since its last feature addition in v1.1.0 in April 2021. Key differentiators include its reliance on `teleport` for efficient DOM management, built-in accessibility (A11Y) features, and support for Server-Side Rendering (SSR) by requiring a pre-defined teleport target in the HTML. It provides essential modal functionalities like add/remove, visibility control, transitions, and automatic keyboard/mouse binding for closing, making it a robust solution for managing modals in modern Vue applications.","status":"active","version":"1.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/hoiheart/vue-universal-modal","tags":["javascript","Vue","VueJS","Vue3","modal","Vue modal","VueJS modal","Vue3 modal","typescript"],"install":[{"cmd":"npm install vue-universal-modal","lang":"bash","label":"npm"},{"cmd":"yarn add vue-universal-modal","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-universal-modal","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Vue 3 applications.","package":"vue","optional":false}],"imports":[{"note":"The library primarily ships as an ES module for Vue 3. CommonJS `require` is not the idiomatic way to import.","wrong":"const VueUniversalModal = require('vue-universal-modal');","symbol":"VueUniversalModal","correct":"import VueUniversalModal from 'vue-universal-modal';"},{"note":"The core CSS styles for the modal are provided separately and must be imported to apply default styling. This should typically be done once in your application's entry point.","symbol":"CSS Styles","correct":"import 'vue-universal-modal/dist/index.css';"},{"note":"The `Modal` component is globally registered when you `app.use(VueUniversalModal, { ... })`. You should use its tag name directly in your templates. If you customized `modalComponent` option during installation, use that custom name.","symbol":"Modal Component","correct":"<Modal v-model=\"isShow\">...</Modal>"}],"quickstart":{"code":"import { createApp, ref, defineComponent } from 'vue';\nimport VueUniversalModal from 'vue-universal-modal';\nimport 'vue-universal-modal/dist/index.css';\n\n// Assuming you have an index.html with <div id=\"app\"></div> and <div id=\"modals\"></div>\nconst app = createApp({\n  template: `\n    <p>\n      <button @click=\"showModal\">Show modal</button>\n    </p>\n    <Modal v-model=\"isShow\" :close=\"closeModal\">\n      <div class=\"modal-content\">\n        <p>Hello from Universal Modal!</p>\n        <button @click=\"closeModal\">Close Modal</button>\n      </div>\n    </Modal>\n  `,\n  setup() {\n    const isShow = ref(false);\n\n    function showModal() {\n      isShow.value = true;\n    }\n\n    function closeModal() {\n      isShow.value = false;\n    }\n\n    return {\n      isShow,\n      showModal,\n      closeModal,\n    };\n  },\n});\n\napp.use(VueUniversalModal, {\n  teleportTarget: '#modals',\n  modalComponent: 'Modal', // Default, explicitly set for clarity\n});\n\napp.mount('#app');\n\n// Basic CSS for demonstration (include in your main CSS or style block)\n// .modal-content {\n//   width: 300px;\n//   padding: 30px;\n//   box-sizing: border-box;\n//   background-color: #fff;\n//   font-size: 20px;\n//   text-align: center;\n// }","lang":"typescript","description":"This quickstart demonstrates how to install `vue-universal-modal` as a Vue 3 plugin and integrate a basic modal into a component using `v-model` for visibility control."},"warnings":[{"fix":"Migrate from `v-if=\"isShow\"` to `v-model=\"isShow\"` on your `<Modal>` component. Ensure your `close` prop function updates the v-model bound variable.","message":"The modal component's visibility control changed from using `v-if` to `v-model`. Using `v-if` will prevent close animations from working correctly, and the `emitClose` slot argument was deprecated.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Ensure your project is running Vue 3. If you are on Vue 2, you will need to find an alternative modal solution or migrate your application to Vue 3.","message":"This plugin is exclusively designed for Vue 3. It does not support Vue 2 applications, and attempting to use it will result in errors related to Vue 3 specific features like `teleport`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Add a target HTML element (e.g., `<div id=\"modals\"></div>`) to your `index.html` file, typically just before the closing `</body>` tag, and configure the plugin with `teleportTarget: '#modals'` (or your chosen selector).","message":"The `teleportTarget` option, which specifies where the modal content is rendered in the DOM, must point to an element that is already present in your `index.html` file. This is particularly important for Server-Side Rendering (SSR) environments.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Apply your custom CSS to the content within the `<Modal>` slot and, if necessary, override default styles or provide your own for the modal backdrop and container via CSS.","message":"While the plugin handles basic modal functionality, it does not provide custom styling out-of-the-box beyond a minimal `index.css`. Developers are expected to provide their own styles for the modal content and potentially the overlay.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `app.use(VueUniversalModal, { ... })` is called before mounting your app, and that you are using the correct `modalComponent` name (default is 'Modal') in your template.","cause":"The `Modal` component either wasn't globally registered, or the `modalComponent` option in `app.use()` was changed to a different name.","error":"[Vue warn]: Failed to resolve component: Modal"},{"fix":"This plugin is for Vue 3. Ensure you are importing `createApp` from 'vue' and calling `app.use()` on the application instance returned by `createApp()`.","cause":"Attempting to use `VueUniversalModal` with Vue 2's `Vue.use()` syntax or an incorrect Vue instance.","error":"TypeError: app.use is not a function"},{"fix":"Change the usage from `<Modal v-if=\"isShow\" ...>` to `<Modal v-model=\"isShow\" ...>`. The `v-model` directive correctly manages the presence of the component in the DOM for transitions.","cause":"The modal's visibility is being controlled with `v-if` instead of `v-model`, preventing Vue's transition system from hooking into the component's lifecycle for animations.","error":"Modal does not show or close with smooth animations, it just appears/disappears instantly."}],"ecosystem":"npm"}