Skip to content
Sponsored by

MagicModal

MagicModal is a flexible, unstyled modal component. Useful for things like confirmation dialogs, detail views, and forms.

<template>
  <m-button @click="modalApi.open">Open Modal</m-button>
  <magic-modal id="magic-modal-default-demo" :options="{ focusTrap: false }">
    <div class="bg-surface-elevation-high aspect-[4/3] w-[40rem] rounded-md" />
  </magic-modal>
</template>

<script lang="ts" setup>
import { MButton } from '@maas/mirror/vue'
import { useMagicModal } from '@maas/vue-equipment/plugins'

const modalApi = useMagicModal('magic-modal-default-demo')
</script>

Overview

Anatomy

vue
<template>
  <magic-modal id="your-modal-id">
    <!-- your content -->
  </magic-modal>
</template>

<script setup>
const { open } = useMagicModal('your-modal-id')
</script>

Installation

CLI

Add @maas/vue-equipment to your dependencies.

sh
pnpm install @maas/vue-equipment
sh
npm install @maas/vue-equipment
sh
yarn add @maas/vue-equipment
sh
bun install @maas/vue-equipment

Vue

If you are using Vue, import and add MagicModalPlugin to your app.

js
import { createApp } from 'vue'
import { MagicModalPlugin } from '@maas/vue-equipment/plugins'

const app = createApp({})

app.use(MagicModalPlugin)

Nuxt

The modal is available as a Nuxt module. In your Nuxt config file add @maas/vue-equipment/nuxt to your modules and add MagicModal to the plugins in your configuration.

js
export default defineNuxtConfig({
  modules: ['@maas/vue-equipment/nuxt'],
  vueEquipment: {
    plugins: ['MagicModal'],
  },
})

Direct Import

If you prefer a more granular approach, the modal can also be directly imported into any Vue component.

vue
<script setup>
import { MagicModal } from '@maas/vue-equipment/plugins'
</script>

<template>
  <magic-modal id="your-modal-id">
    <!-- your content -->
  </magic-modal>
</template>

Composable

In order to interact with the modal from anywhere within your app, we provide a useMagicModal composable. Import it directly when needed.

js
import { onMounted } from 'vue'
import { useMagicModal } from '@maas/vue-equipment/plugins'

const { open } = useMagicModal('your-modal-id')

onMounted(() => {
  open()
})

TIP

If you have installed the modal as a Nuxt module, the composable will be auto-imported and is automatically available in your Nuxt app.

Peer Dependencies

If you haven’t installed the required peer dependencies automatically, you’ll need to install the following packages manually.

Installation

sh
pnpm install @nuxt/kit @vueuse/core @vueuse/integrations defu focus-trap
sh
npm install @nuxt/kit @vueuse/core @vueuse/integrations defu focus-trap
sh
yarn add @nuxt/kit @vueuse/core @vueuse/integrations defu focus-trap
sh
bun install @nuxt/kit @vueuse/core @vueuse/integrations defu focus-trap

API Reference

Props

The modal comes with a simple set of props. Only the id is required.

PropTypeRequired
id
MaybeRef<string>true
options
MagicModalOptionsfalse

Options

To customize the modal override the necessary options. Any custom options will be merged with the default options.

OptionTypeDefault
backdrop
booleantrue
tag
string
'dialog'
focusTrap
boolean | FocusTrapOptionsobject
scrollLock
boolean | objectobject
scrollLock.padding
booleantrue
teleport.target
string'body'
teleport.disabled
booleanfalse
transition.content
string'magic-modal-content'
transition.backdrop
string'magic-modal-backdrop'
keyListener.close
string[]['Escape']

CSS Variables

In order to provide its basic functionality the modal comes with some CSS. To ensure that the modal is customizable, relevant values are available as CSS variables.

VariableDefault
--magic-modal-z-index999
--magic-modal-content-align-itemscenter
--magic-modal-content-justify-contentcenter
--magic-modal-content-overflow-yauto
--magic-modal-backdrop-colorrgba(0, 0, 0, 0.5)
--magic-modal-backdrop-filterunset