Setup

How to start with Vue Final Modal, by creating a fresh new project or adding it to your Vue application.

Play online

You can start playing with Vue Final Modal in your browser using our online sandboxes:

Installation

yarn add vue-final-modal

npm install vue-final-modal

pnpm add vue-final-modal

Plugin registration

In vue-final-modal 4, it's necessary to create a plugin by createVfm() and register it because vue-final-modal 4 has some shared context that is based on provide/inject.

Vue 3

import { createApp } from 'vue'
import { createVfm } from 'vue-final-modal'
import App from './App.vue'
const app = createApp(App)
const vfm = createVfm()
app.use(vfm).mount('#app')

Nuxt 3

import { createVfm } from 'vue-final-modal'
export default defineNuxtPlugin((nuxtApp) => {
  const vfm = createVfm() as any
  nuxtApp.vueApp.use(vfm)
})

Import required CSS

vue-final-modal 4 has tiny size of required CSS (gzipped 0.49kb). All classes have a .vfm- prefix, so you don't have to worry about any CSS pollution. See style of <VueFinalModal>.

Vue 3

import 'vue-final-modal/style.css'

Nuxt 3

export default defineNuxtConfig({
  css: ['vue-final-modal/style.css'],
})

Add <ModalsContainer> to Vue tree

<ModalsContainer> is a container for the dynamic modals that created by useModal().

You don't need to do add anything else to the <ModalsContainer>, as long as you include it in your Vue tree, you can use Dynamic modals.

You only need to put it once in your Vue app.

Vue 3

<script setup lang="ts">
import { ModalsContainer } from 'vue-final-modal'
</script>
<template>
  <div>
    ...
    <ModalsContainer />
  </div>
</template>

Nuxt 3

<script setup lang="ts">
import { ModalsContainer } from 'vue-final-modal'
</script>
<template>
  <div>
    Some default layout shared across all pages
    <slot />
    <ModalsContainer />
  </div>
</template>

Style a modal

Define a styled modal for yourself. Here will create a styled <ModalConfirm> with <VueFinalModal> as an example.

Plain CSS

Use plain CSS to define a <ModalConfirmPlainCss> component with <VueFinalModal>.

• Basic example
  PreviewPreview.vueModalConfirmPlainCss.vue

  Open Modal

  Preview.vue

    <script setup lang="ts">
    import { ModalsContainer, useModal } from 'vue-final-modal'
    import ModalConfirmPlainCss from './ModalConfirmPlainCss.vue'
    const { open, close } = useModal({
      component: ModalConfirmPlainCss,
      attrs: {
        title: 'Hello World!',
        onConfirm() {
          close()
        },
      },
      slots: {
        default: '<p>The content of the modal</p>',
      },
    })
    </script>
    <template>
      <VButton @click="open">
        Open Modal
      </VButton>
      <ModalsContainer />
    </template>

  Copy to clipboard

  ModalConfirmPlainCss.vue

    <script setup lang="ts">
    import { VueFinalModal } from 'vue-final-modal'
    defineProps<{
      title?: string
    }>()
    const emit = defineEmits<{
      (e: 'confirm'): void
    }>()
    </script>
    <template>
      <VueFinalModal
        class="confirm-modal"
        content-class="confirm-modal-content"
        overlay-transition="vfm-fade"
        content-transition="vfm-fade"
      >
        <h1>{{ title }}</h1>
        <slot />
        <button @click="emit('confirm')">
          Confirm
        </button>
      </VueFinalModal>
    </template>
    <style>
    .confirm-modal {
      display: flex;
      justify-content: center;
      align-items: center;
    }
    .confirm-modal-content {
      display: flex;
      flex-direction: column;
      padding: 1rem;
      background: #fff;
      border-radius: 0.5rem;
    }
    .confirm-modal-content > * + *{
      margin: 0.5rem 0;
    }
    .confirm-modal-content h1 {
      font-size: 1.375rem;
    }
    .confirm-modal-content button {
      margin: 0.25rem 0 0 auto;
      padding: 0 8px;
      border: 1px solid;
      border-radius: 0.5rem;
    }
    .dark .confirm-modal-content {
      background: #000;
    }
    </style>

  Copy to clipboard

Atomic CSS (Recommended)

Let's take TailwindCSS for example to define a <ModalConfirm> component with <VueFinalModal>.

• Basic example
  PreviewPreview.vueModalConfirm.vue

  Open Modal

  Preview.vue

    <script setup lang="ts">
    import { ModalsContainer, useModal } from 'vue-final-modal'
    import ModalConfirm from './ModalConfirm.vue'
    const { open, close } = useModal({
      component: ModalConfirm,
      attrs: {
        title: 'Hello World!',
        onConfirm() {
          close()
        },
      },
      slots: {
        default: '<p>UseModal: The content of the modal</p>',
      },
    })
    </script>
    <template>
      <VButton @click="() => open()">
        Open Modal
      </VButton>
      <ModalsContainer />
    </template>

  Copy to clipboard

  ModalConfirm.vue

    <script setup lang="ts">
    import { VueFinalModal } from 'vue-final-modal'
    defineProps<{
      title?: string
    }>()
    const emit = defineEmits<{
      (e: 'confirm'): void
    }>()
    </script>
    <template>
      <VueFinalModal
        class="flex justify-center items-center"
        content-class="flex flex-col max-w-xl mx-4 p-4 bg-white dark:bg-gray-900 border dark:border-gray-700 rounded-lg space-y-2"
      >
        <h1 class="text-xl">
          {{ title }}
        </h1>
        <slot />
        <button class="mt-1 ml-auto px-2 border rounded-lg" @click="emit('confirm')">
          Confirm
        </button>
      </VueFinalModal>
    </template>

  Copy to clipboard

Control a modal

There are three ways to control a modal component.

Take the <ModalConfirm> component we built on previous section as an example:

useModal()

useModal() is a composable function that is used to create a dynamic modal, then you can control the modal programmatically.

As a requirement to using useModal() you must add <ModalsContainer> to your main App.vue file.

• Basic example
  PreviewPreview.vue

  Open Modal

  Preview.vue

    <script setup lang="ts">
    import { ModalsContainer, useModal } from 'vue-final-modal'
    import ModalConfirm from './ModalConfirm.vue'
    const { open, close } = useModal({
      component: ModalConfirm,
      attrs: {
        title: 'Hello World!',
        onConfirm() {
          close()
        },
      },
      slots: {
        default: '<p>UseModal: The content of the modal</p>',
      },
    })
    </script>
    <template>
      <VButton @click="() => open()">
        Open Modal
      </VButton>
      <ModalsContainer />
    </template>

  Copy to clipboard

v-model

Use v-model for show/hide a modal.

• Basic example
  PreviewPreview.vue

  Open Modal

  Preview.vue

    <script setup lang="ts">
    const show = ref(false)
    function confirm() {
      show.value = false
    }
    </script>
    <template>
      <VButton @click="show = true">
        Open Modal
      </VButton>
      <ModalConfirm
        v-model="show"
        title="Hello World!"
        @confirm="() => confirm()"
      >
        <p>VModel: The content of the modal</p>
      </ModalConfirm>
    </template>

  Copy to clipboard

modalId

modelValue is not a required prop for <VueFinalModal>. Without using v-model, you can also use useVfm() composable function to control the modal by given a modalId.

• Basic example
  PreviewPreview.vue

  Open Modal

  Preview.vue

    <script setup lang="ts">
    import { useVfm } from 'vue-final-modal'
    const vfm = useVfm()
    const modalId = Symbol('modalId')
    function confirm() {
      vfm.close(modalId)
    }
    </script>
    <template>
      <VButton @click="() => vfm.open(modalId)">
        Open Modal
      </VButton>
      <ModalConfirm
        :modal-id="modalId"
        title="Hello World!"
        @confirm="() => confirm()"
      >
        <p>The content of the modal</p>
      </ModalConfirm>
    </template>

  Copy to clipboard