VModal

The VModal component is a powerful tool for displaying content that sits above the main window. It is commonly used for modals, popups, or dialog boxes. This highly flexible component allows for easy content customization and is an essential tool for many interactive interfaces.

Usage

Modals are commonly used to focus the user's attention on a specific task or information. The VModal component can be easily integrated into your application to display content, collect user input, or present options. With properties and slots provided by VModal, you can customize its appearance and behavior. The modal's visibility can be controlled with the v-model directive, and you can add custom content, headers, and footers using Vue's slot system.

Below are some examples to illustrate how to use and customize the VModal component within your application.

Default Content

<template>
  <VModal v-model="opened" header="Modal Title">
    Phasellus faucibus aliquam arcu, eu laoreet lacus aliquet malesuada. Praesent finibus bibendum ligula non commodo. Mauris maximus nisl vitae metus euismod, et vestibulum ex dignissim. Phasellus accumsan feugiat risus sit amet venenatis. Phasellus congue felis a arcu eleifend, sit amet malesuada enim accumsan. Duis id dolor sit amet tellus ullamcorper pretium sollicitudin porttitor mi. Donec at tortor purus. Etiam non ex at nulla faucibus gravida.
  </VModal>
  <VButton @click="opened = !opened">Open modal</VButton>
</template>

Custom header

Instead of using the header prop, you can use the header slot to customize the header content.

<template>
  <VModal v-model="opened">
    <template #header>
      <div class="text-blue-600">My custom header</div>
    </template>
    Phasellus faucibus aliquam arcu, eu laoreet lacus aliquet malesuada. Praesent finibus bibendum ligula non commodo. Mauris maximus nisl vitae metus euismod, et vestibulum ex dignissim. Phasellus accumsan feugiat risus sit amet venenatis. Phasellus congue felis a arcu eleifend, sit amet malesuada enim accumsan. Duis id dolor sit amet tellus ullamcorper pretium sollicitudin porttitor mi. Donec at tortor purus. Etiam non ex at nulla faucibus gravida.
  </VModal>
  <VButton @click="opened = !opened">Open modal</VButton>
</template>

The footer slot can be used to provide custom content in the footer of the modal.

<template>
  <VModal v-model="opened" header="My modal">
    Phasellus faucibus aliquam arcu, eu laoreet lacus aliquet malesuada. Praesent finibus bibendum ligula non commodo. Mauris maximus nisl vitae metus euismod, et vestibulum ex dignissim. Phasellus accumsan feugiat risus sit amet venenatis. Phasellus congue felis a arcu eleifend, sit amet malesuada enim accumsan. Duis id dolor sit amet tellus ullamcorper pretium sollicitudin porttitor mi. Donec at tortor purus. Etiam non ex at nulla faucibus gravida.
    <template #footer>
      <div class="text-blue-600">Custom footer 🔥</div>
    </template>
  </VModal>
  <VButton @click="opened = !opened">Open modal</VButton>
</template>

Interaction with the Document

Two key properties of the VModal component are appendToBody and scrollBody.

The appendToBody property determines whether the modal is appended to the body of your document. This feature can be especially useful in managing stacking context and z-index in complex layouts or with nested elements.

The scrollBody property, on the other hand, can be used to control body scrolling when the modal is open. By setting scrollBody to false, you can prevent the body from scrolling while the modal is active, helping to maintain the user's focus on the modal content.

These properties provide additional control over how the modal interacts with the rest of your application, ensuring a smooth user experience.

Configuration

Here the CardConfig interface:

export interface ModalConfig extends DefaultConfig {
  overlay: {
    // TODO: Handle dynamic injection
    transition: ConfigTransitionConfig,
    class: MethodOrStringType,
  },
  backdrop: {
    wrapper: MethodOrStringType,
    class: MethodOrStringType
  },
  wrapper: MethodOrStringType,
  modal: {
    wrapper: MethodOrStringType,
    rounded: MethodOrObject, // Contain all rounded key / value
    transition: ConfigTransitionConfig,
    // Config for default slot injected with title props
    header: {
      class: MethodOrStringType,
      close: {
        class: MethodOrStringType,
        icon: IconType,
        sizes?: MethodOrObject, // Contain all sizes key / value
        size?: MethodOrStringType,
      }
    },
    content: {
      class: MethodOrStringType
    },
    footer: {
      class: MethodOrStringType
    }
  }
}

The VModel preset configuration interface extends the DefaultConfig interface, which is explained in detail here.

Props

PropTypeDefaultDescription
headerString-Adds a header title to the modal.
modelValueBoolean-Controls the visibility of the modal. Use the v-model directive to control this property.
preventCloseBooleanfalseIf set to true, prevents the modal from being closed when the backdrop is clicked.
hideCloseBooleanfalseDetermines whether to hide the close button.
appendToBodyBooleantrueDetermines whether to append the modal to the body of the HTML document.
scrollBodyBooleanfalseControls whether the body of the document can be scrolled when the modal is open.
sizeString-Sets the size of the modal. Acceptable values are: sm, md, lg, xl, full.
roundedString, Boolean-Determines the border-radius of the modal. If a string is provided, it should be one of the predefined border radius values: sm, md, lg, xl, full.
configObject-Allows to customize the modal through the config prop. This prop is automatically provided by the Vunix config composable.
Edit this page on GitHub