Vue Universal Modal

Common errors

• [Vue warn]: Failed to resolve component: Modal

  cause The `Modal` component either wasn't globally registered, or the `modalComponent` option in `app.use()` was changed to a different name.
  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.

• TypeError: app.use is not a function

  cause Attempting to use `VueUniversalModal` with Vue 2's `Vue.use()` syntax or an incorrect Vue instance.
  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()`.

• Modal does not show or close with smooth animations, it just appears/disappears instantly.

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

Warnings

• breaking 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.
  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.
• breaking 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`.
  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.
• gotcha 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.
  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).
• gotcha 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.
  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.

Install

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

Imports

• VueUniversalModal
  wrong:

  const VueUniversalModal = require('vue-universal-modal');

  correct:

  import VueUniversalModal from 'vue-universal-modal';

  The library primarily ships as an ES module for Vue 3. CommonJS `require` is not the idiomatic way to import.
• CSS Styles

  import 'vue-universal-modal/dist/index.css';

  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.
• Modal Component

  <Modal v-model="isShow">...</Modal>

  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.

Quickstart

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.

import { createApp, ref, defineComponent } from 'vue';
import VueUniversalModal from 'vue-universal-modal';
import 'vue-universal-modal/dist/index.css';

// Assuming you have an index.html with <div id="app"></div> and <div id="modals"></div>
const app = createApp({
  template: `
    <p>
      <button @click="showModal">Show modal</button>
    </p>
    <Modal v-model="isShow" :close="closeModal">
      <div class="modal-content">
        <p>Hello from Universal Modal!</p>
        <button @click="closeModal">Close Modal</button>
      </div>
    </Modal>
  `,
  setup() {
    const isShow = ref(false);

    function showModal() {
      isShow.value = true;
    }

    function closeModal() {
      isShow.value = false;
    }

    return {
      isShow,
      showModal,
      closeModal,
    };
  },
});

app.use(VueUniversalModal, {
  teleportTarget: '#modals',
  modalComponent: 'Modal', // Default, explicitly set for clarity
});

app.mount('#app');

// Basic CSS for demonstration (include in your main CSS or style block)
// .modal-content {
//   width: 300px;
//   padding: 30px;
//   box-sizing: border-box;
//   background-color: #fff;
//   font-size: 20px;
//   text-align: center;
// }