useModal()

A composable function to define a dynamic modal.

With useModal(), that means you don't have to add the modal to your Vue template and you don't have to use v-model or modalId to open or close the modal. You can simply use it to create a dynamic modal everywhere and control it programmatically.

Prerequisite

Using useModal() to control dynamic modal must add <ModalsContainer /> to your main App.vue file like so:

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

<template>
  <div>
    ...
    <ModalsContainer />
  </div>
</template>

Usage

Passing Props and Events

import { VueFinalModal, useModal } from 'vue-final-modal'

const { open, close, destroy, options, patchOptions } = useModal({
  // Open the modal or not when the modal was created, the default value is `false`.
  defaultModelValue: false,
  /**
   * If set `keepAlive` to `true`: 
   * 1. The `displayDirective` will be set to `show` by default. 
   * 2. The modal component will not be removed after the modal closed until you manually execute `destroy()`. 
   */
  keepAlive: false,
  // `component` is optional and the default value is `<VueFinalModal>`.
  component: VueFinalModal,
  attrs: {
    // Bind props to the modal component (VueFinalModal in this case).
    clickToClose: true,
    escToClose: true,
    // Bind events to the modal component (VueFinalModal in this case).
    // Any custom events can be listened for when prefixed with "on", e.g. "onEventName".
    onBeforeOpen() { /* on before open */ },
    onOpened() { /* on opened */ },
    onBeforeClose() { /* on before close */ },
    onClosed() { /* on closed */ },
  }
})

// Open the modal
open().then(() => { /* Do something after modal opened */ })
// Close the modal
close().then(() => { /* Do something after modal closed */ })
// Destroy the modal manually, it only be needed when the `keepAlive` is set to `true`
destroy()
// Checkout the modal options
options // the state of the dynamic modal

// Overwrite the modal options
patchOptions({
  attrs: {
    // Overwrite the modal's props
    clickToClose: false,
    escToClose: false,
  }
})

Passing Slots

with String

import { VueFinalModal, useModal } from 'vue-final-modal'

const modalInstance = useModal({
  component: VueFinalModal,
  attrs: { ... },
  slots: {
    default: '<p>The content of the modal</p>'
  }
})
Security Note: https://vuejs.org/api/built-in-directives.html#v-html Dynamically rendering arbitrary HTML on your website can be very dangerousbecause it can easily lead to XSS attacks. Only use v-html on trusted content and never on user-provided content.

with Component

import { VueFinalModal, useModal } from 'vue-final-modal'
// ModalContent is the component you want to put into the modal content
import ModalContent from './ModalContent.vue'


const modalInstance = useModal({
  component: VueFinalModal,
  attrs: { ... },
  slots: {
    // You can import your own component as a slot and put it to `slots.default` without binding props and events.
    default: ModalContent
  }
})

with Component, Props and Events

import { VueFinalModal, useModal, useModalSlot } from 'vue-final-modal'
// ModalContent is the component you want to put into the modal content
import ModalContent from './ModalContent.vue'

const modalInstance = useModal({
  component: VueFinalModal,
  attrs: { ... },
  slots: {
    default: useModalSlot({
      component: ModalContent,
      attrs: {
        // Bind ModalContent props
        title: 'Hello world!'
        // Bind ModalContent events
        onConfirm() {  }
      }
    })
  }
})
useModalSlot() is a function that provides better DX for type checking. It just returns the same object you passed in.

Type Declarations

Checkout Types section.
Table of Contents