MagicModal

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

Preview

Code

<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

• Overview
• Anatomy
• Installation
• Peer Dependencies
• API Reference

Anatomy

<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.

pnpm

pnpm install @maas/vue-equipment

npm

npm install @maas/vue-equipment

yarn

yarn add @maas/vue-equipment

bun

bun install @maas/vue-equipment

Vue

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

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.

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.

<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.

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.

Package
@nuxt/kit
@vueuse/core
@vueuse/integrations
defu
focus-trap

Installation

pnpm

pnpm install @nuxt/kit @vueuse/core @vueuse/integrations defu focus-trap

npm

npm install @nuxt/kit @vueuse/core @vueuse/integrations defu focus-trap

yarn

yarn add @nuxt/kit @vueuse/core @vueuse/integrations defu focus-trap

bun

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.

Prop	Type	Required
id	MaybeRef<string>	true
options	MagicModalOptions	false

Options

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

Option	Type	Default
backdrop	boolean	true
tag	string	'dialog'
focusTrap	boolean | FocusTrapOptions	object
scrollLock	boolean | object	object
scrollLock.padding	boolean	true
teleport.target	string	'body'
teleport.disabled	boolean	false
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.

Variable	Default
--magic-modal-z-index	999
--magic-modal-content-align-items	center
--magic-modal-content-justify-content	center
--magic-modal-content-overflow-y	auto
--magic-modal-backdrop-color	rgba(0, 0, 0, 0.5)
--magic-modal-backdrop-filter	unset