MagicDrawer

MagicDrawer is a flexible, touch enabled, unstyled drawer component. Useful for things like shopping carts, menus, as a modal replacement on mobile devices and the like.

Preview

Code

<template>
  <m-button @click="drawerApi.open">Open Drawer</m-button>
  <magic-drawer id="magic-drawer-demo" :options="{ focusTrap: false }">
    <div class="bg-surface-elevation-base absolute inset-0" />
  </magic-drawer>
</template>

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

const drawerApi = useMagicDrawer('magic-drawer-demo')
</script>

Overview

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

Anatomy

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

<script setup>
const { open } = useMagicDrawer('your-drawer-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 MagicDrawerPlugin to your app.

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

const app = createApp({})

app.use(MagicDrawerPlugin)

Nuxt

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

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

Direct Import

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

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

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

Composable

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

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

const { open } = useMagicDrawer('your-drawer-id')

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

TIP

If you have installed the drawer 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
wheel-gestures

Installation

pnpm

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

npm

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

yarn

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

bun

bun install @nuxt/kit @vueuse/core @vueuse/integrations defu focus-trap wheel-gestures

API Reference

Props

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

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

Options

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

Option	Type	Default
position	string	'bottom'
backdrop	boolean	true
tag	string	'dialog'
focusTrap	boolean | FocusTrapOptions	object
scrollLock	boolean | object	object
scrollLock.padding	boolean	true
snapPoints	DrawerSnapPoint[]	[1]
teleport.target	string	'body'
teleport.disabled	boolean	false
transition.content	string	'magic-drawer--content'
transition.backdrop	string	'magic-drawer--backdrop'
threshold.lock	number	0
threshold.distance	number	128
threshold.momentum	number	1
animation.snap.duration	number	300
animation.snap.easing	function	function
initial.open	boolean	false
initial.transition	boolean	—
initial.snapPoint	DrawerSnapPoint	—
keyListener	boolean | object	object
keyListener.close	string[]	['Escape']
enableMousewheel	boolean	false
preventZoom	boolean	true
preventDragClose	boolean	false
disabled	boolean	false

CSS Variables

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

Variable	Default
--magic-drawer-height	75svh
--magic-drawer-width	100%
--magic-drawer-max-height	none
--magic-drawer-max-width	none
--magic-drawer-content-height	100%
--magic-drawer-justify-content	center
--magic-drawer-align-items	flex-end
--magic-drawer-enter-animation	slide-btt-in 300ms ease
--magic-drawer-enter-animation	slide-btt-out 300ms ease
--magic-drawer-drag-overshoot	4rem

Caveats

The drawer handles situations where dragging and scrolling might interfer with each other on touch devices. In order for the drawer to differentiate when the user scrolls and when the user drags, any scrollable containers within the drawer need to have their overflow value explicitely set to 'auto' or 'scroll'.

Examples

Vertical

Preview

Code

<template>
  <m-button @click="drawerApi.open">Open Drawer</m-button>
  <magic-drawer id="magic-drawer-vertical-demo" :options="{ focusTrap: false }">
    <div class="bg-surface-elevation-base absolute inset-0" />
  </magic-drawer>
</template>

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

const drawerApi = useMagicDrawer('magic-drawer-vertical-demo')
</script>

Horizontal

Preview

Code

<template>
  <m-button @click="drawerApi.open">Open Drawer</m-button>
  <magic-drawer
    id="magic-drawer-horizontal-demo"
    :options="{ focusTrap: false, position: 'right' }"
  >
    <div class="bg-surface-elevation-base absolute inset-0" />
  </magic-drawer>
</template>

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

const drawerApi = useMagicDrawer('magic-drawer-horizontal-demo')
</script>

<style>
[data-id='magic-drawer-horizontal-demo'] {
  --magic-drawer-height: 100svh;
  --magic-drawer-width: 20rem;
}
</style>

Snap Points

Preview

Code

<template>
  <m-button @click="drawerApi.open">Open Drawer</m-button>
  <magic-drawer
    id="magic-drawer-snap-points-demo"
    :options="{
      focusTrap: false,
      snapPoints: snapPoints,
      initial: { snapPoint: snapPoints[0] },
    }"
  >
    <div class="bg-surface-elevation-base absolute inset-0" />
  </magic-drawer>
</template>

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

const snapPoints = ['320px', 0.75, 1]
const drawerApi = useMagicDrawer('magic-drawer-snap-points-demo')
</script>

<style>
[data-id='magic-drawer-snap-points-demo'] {
  --magic-drawer-height: 100svh;
}
</style>

Mousewheel

Preview

Code

<template>
  <m-button @click="drawerApi.open">Open Drawer</m-button>
  <magic-drawer
    id="magic-drawer-mousewheel-demo"
    :options="{ focusTrap: false, enableMousewheel: true }"
  >
    <div class="bg-surface-elevation-base absolute inset-0" />
  </magic-drawer>
</template>

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

const drawerApi = useMagicDrawer('magic-drawer-mousewheel-demo')
</script>