vue-neat-modal

Vue Neat Modal

Highly flexible and customizable Vue 3 Modal window component.

Demos on CodeSandbox

Why Vue Neat Modal ?

The modal uses Vue 3 portal feature to detach modal to documents root, no more overflow: hidden; and z-index hacks and limitations, nest it as much as you want it will always work as expected.

This library gives you the core functionality of the Modal Window and exposes an empty modal content slot where you can put whatever you want.

No default card, button, title and e.t.c. is rendered as you may see in many other, modal component plugins, this gives possibility to render anything you like inside the modal, no need for style overriding.

It offers a nice global props configuration so that you can set common props for your projects modals so you don't repeat them everytime the modal is used.

There are much more exciting features, check the usage docs down below.

Basic usage

Install: npm install vue-neat-modal -S

Import the styles in your main entry file

  import 'vue-neat-modal/dist/vue-neat-modal.css'

Local component registration:

  // Import the component
  import { Modal } from 'vue-neat-modal'

  export default {
    // Register it
    components: { Modal }
  }

Global registration:

  // Import the component
  import { Modal } from 'vue-neat-modal'

  // Register it globally with default component name option 
  app.component(Modal.name, Modal)

  // Or register with custom name
  app.component('AppModal', Modal)

Usage, simplest without a model

  <template>
    <Modal max-width="500px">
      <template #activator="props">
        <button v-bind="props">
          Open Modal
        </button>
      </template>

      <template #default="{ close }">
        <div>
          Modal Content

          <button @click="close">
            Close
          </button>
        </div>
      </template>
    </Modal>
  </template>

Usage with a model variable

  <template>
    <Modal v-model="isOpen" max-width="500px">
      <div>
        Modal Content

        <button @click="isOpen = false">
          Close
        </button>
      </div>
    </Modal>
  
    <button @click="isOpen = !isOpen">Open Modal</button>
  </template>

  <script>
    export default {
      data: () => ({
        isOpen: false,
      })
    }
  </script>

You can use slot props for convienience, and still keep a model it is totally fine.

  <template>
    <Modal max-width="500px" v-model="isOpen">
      <template #activator="props">
        <button v-bind="props">
          Open Modal
        </button>
      </template>

      <template #default="{ close }">
        <div>
          Modal Content

          <button @click="close">
            Close
          </button>
        </div>
      </template>
    </Modal>
  </template>

  <script>
    export default {
      data: () => ({
        isOpen: false,
      })
    }
  </script>

Feel free to mix and match slots / model control, everything is synced. For instance if you want you can remove activator, while still keeping the default slot prop which exposes a nice close method for convinience. Then you can toggle modal from anywhere else through model variable.

Modal Transitions

You can easily change the transition of the modal content by setting modalTransition prop

  <template>
    <Modal modal-transition="slide-down">
      <div>
        Now I will slide down instead of scale =)
      </div>
    </Modal>
  </template>

By default Vue Neat Modal provides 5 transitions for modalTransition

Those are: scale, slide-down, slide-up, move-down, move-up

For non-fullscreen modals avoid using move-down and move-up because they perform nicely only with fullscreen modals when there is a block that fully covers the screen which can fully move down or up by it's height.

You can easily create your own transition and pass the name of it as prop, under the hood it just passes it to Vue's transition component, no magic happening here =)

Global Default Props

You can set global default props for all of your modals to prevent repetition, for instance if you want all of your modals transition be slide-down instead of it's default scale.

In your main entry file

  // Import helper function 
  import { setDefaultProps } from 'vue-neat-modal'

  // Call it and pass object
  setDefaultProps({
    // Now all of your modals will have slide-down by default
    modalTransition: 'slide-down',

    // You can pass any valid modal props...
  })

Props

prop	desc	type	default
modelValue	Value which controls the visibility	boolean	false
alignX	Horizontal alignment of the modal, available values: left, center, right	string	"center"
alignY	Vertical alignment of the modal, available values: top, center, bottom	string	"center"
noSpacing	Remove margin on modal	string	false
clickOut	Whether click out closes the modal or not	boolean	true
eager	Controls whether component should mount immediately even if it has not been opened	boolean	false
teleportTarget	Where should modal be detached to.	string | HTMLElement	"#app"
backdropTransition	Backdrop overlays transition	string	undefined
modalTransition	The modal content transition	string	"scale"
disableMotion	Disable transition on backdrop and modal	boolean	false
removeBackdrop	Do not render backdrop	boolean	false
width	The width css property of the modal	string	"auto"
maxWidth	The max-width css property of the modal	string	"none"
fullscreen	Makes content cover whole modal, and removes spacing	boolean	false
backdropClass	Add class to backdrop	string	undefined
wrapperClass	Add class to wrapper	string	undefined
modalClass	Add class to modal	string	undefined

Events

name	desc
after-enter	Modal is fully opened and animations are ended
after-leave	Modal is fully hidden and animations are ended