MagicTray

MagicTray is a flexible, touch enabled, unstyled component that clips its content with a draggable, snapping clip path. Useful for things like peeking panels, reveal effects, resizable previews and the like.

PreviewCode

Drag the bottom edge

<template>
  <magic-tray
    id="magic-tray-default-demo"
    :options="{
      snapPoints: { bottom: [0, 0.2, 0.4] },
      threshold: { distance: 32 },
    }"
    style="--magic-tray-radius: 0.5rem"
  >
    <template #background>
      <div class="bg-surface-base h-full w-full" />
    </template>
    <div
      class="flex aspect-16/9 w-120 max-w-full items-center justify-center select-none"
    >
      <span>Drag the bottom edge</span>
    </div>
  </magic-tray>
</template>

Overview

Anatomy

MagicTray can be used as a single self-contained component or composed from its individual parts for full control.

Simple

vue

<template>
  <magic-tray
    id="your-tray-id"
    :options="{ snapPoints: { bottom: [0, 0.5, 1] } }"
  >
    <!-- your content -->
  </magic-tray>
</template>

<script setup>
const { snapTo } = useMagicTray('your-tray-id')
</script>

Composed

vue

<template>
  <magic-tray-provider id="your-tray-id" :options="options">
    <magic-tray-content>
      <!-- your content -->
      <template #handle="{ side }">
        <!-- custom handle for `side` -->
      </template>
    </magic-tray-content>
  </magic-tray-provider>
</template>

Installation

CLI

Add @maas/vue-equipment to your dependencies.

pnpmnpmyarnbun

pnpm install @maas/vue-equipment

npm install @maas/vue-equipment

yarn add @maas/vue-equipment

bun install @maas/vue-equipment

Vue

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

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

const app = createApp({})

app.use(MagicTrayPlugin)

Nuxt

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

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

Direct Import

If you prefer a more granular approach, components can be directly imported.

vue

<script setup>
import {
  MagicTrayProvider,
  MagicTrayContent,
  MagicTrayHandle,
} from '@maas/vue-equipment/plugins/MagicTray'
</script>

Composable

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

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

const { snapTo } = useMagicTray('your-tray-id')

onMounted(() => {
  snapTo('bottom', 0.5)
})

TIP

If you have installed the tray 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`
`defu`

Installation

pnpmnpmyarnbun

pnpm install @nuxt/kit @vueuse/core defu

npm install @nuxt/kit @vueuse/core defu

yarn add @nuxt/kit @vueuse/core defu

bun install @nuxt/kit @vueuse/core defu

API Reference

MagicTrayProvider

The MagicTrayProvider wraps the tray and configures all child components according to the provided options.

Props

Prop	Type	Required
`id`	`MaybeRef<string>`	`true`
`options`	`MagicTrayOptions`	`false`

Options

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

Option	Type	Default
`tag`	`string`	`'div'`
`snapPoints`	`TraySnapPoints`	`{ bottom: [0, 0.5, 1] }`
`snap.mode`	`'closest' \| 'step'`	`'closest'`
`drag.mode`	`'free' \| 'snap' \| Partial<Record<MagicTraySide, 'free' \| 'snap'>>`	`'free'`
`handles`	`boolean \| Partial<Record<MagicTraySide, boolean>>`	`true`
`magnetism.sides`	`false \| Partial<Record<MagicTraySide, Partial<Record<MagicTraySnapPoint, 'inner' \| 'outer' \| 'both'>>>>`	`false`
`magnetism.radius`	`number \| { start?: number; stop?: number }`	`0`
`magnetism.pull`	`number`	`0`
`magnetism.easing`	`EasingKey`	`'easeInOutQuad'`
`magnetism.virtual`	`boolean`	`false`
`threshold.lock`	`number`	`0`
`threshold.distance`	`number`	`128`
`threshold.momentum`	`number`	`1`
`animation.snap.duration`	`number`	`300`
`animation.snap.easing`	`function`	`function`
`initial.snapPoints`	`Partial<Record<MagicTraySide, MagicTraySnapPoint>>`	`—`
`initial.transition`	`boolean`	`false`
`disabled`	`boolean`	`false`
`inset`	`boolean`	`false`

MagicTrayContent

Renders the clipped content along with drag and snap behavior. Combines all four sides into a single clip-path.

Slots

Slot	Description
`default`	The content that gets clipped.
`background`	A layer that fills the full content element, including the reserved overshoot padding. Useful to give the tray a background that stays visible while overdragging.
`handle`	Custom handle visuals. Rendered once per draggable side and scoped with the respective `side`.

CSS Variables

Variable	Default
`--magic-tray-radius`	`0px`
`--magic-tray-radius-top-left`	`var(--magic-tray-radius)`
`--magic-tray-radius-top-right`	`var(--magic-tray-radius)`
`--magic-tray-radius-bottom-right`	`var(--magic-tray-radius)`
`--magic-tray-radius-bottom-left`	`var(--magic-tray-radius)`
`--magic-tray-clip-top`	`–`
`--magic-tray-clip-right`	`–`
`--magic-tray-clip-bottom`	`–`
`--magic-tray-clip-left`	`–`
`--magic-tray-drag-overshoot`	`3rem`
`--magic-tray-drag-overshoot-outer`	`var(--magic-tray-drag-overshoot)`
`--magic-tray-drag-overshoot-inner`	`var(--magic-tray-drag-overshoot)`
`--magic-tray-position`	`relative`
`--magic-tray-display`	`inline-block`
`--magic-tray-width`	`max-content`
`--magic-tray-height`	`max-content`
`--magic-tray-max-width`	`none`
`--magic-tray-max-height`	`none`
`--magic-tray-bg-z-index`	`-1`

MagicTrayHandle

Renders an invisible, draggable hit area along an edge. Has no appearance of its own — provide visuals through the handle slot. Rendered automatically by MagicTrayContent for each draggable side.

Slot Props

Prop	Type	Description
`side`	`MagicTraySide`	The side this handle controls.

CSS Variables

Variable	Default
`--magic-tray-handle-width-x`	`100%`
`--magic-tray-handle-width-y`	`4rem`
`--magic-tray-handle-width-top`	`var(--magic-tray-handle-width-x)`
`--magic-tray-handle-width-bottom`	`var(--magic-tray-handle-width-x)`
`--magic-tray-handle-width-left`	`var(--magic-tray-handle-width-y)`
`--magic-tray-handle-width-right`	`var(--magic-tray-handle-width-y)`
`--magic-tray-handle-height-x`	`4rem`
`--magic-tray-handle-height-y`	`100%`
`--magic-tray-handle-height-top`	`var(--magic-tray-handle-height-x)`
`--magic-tray-handle-height-bottom`	`var(--magic-tray-handle-height-x)`
`--magic-tray-handle-height-left`	`var(--magic-tray-handle-height-y)`
`--magic-tray-handle-height-right`	`var(--magic-tray-handle-height-y)`
`--magic-tray-handle-offset-x-top`	`0%`
`--magic-tray-handle-offset-x-right`	`50%`
`--magic-tray-handle-offset-x-bottom`	`0%`
`--magic-tray-handle-offset-x-left`	`-50%`
`--magic-tray-handle-offset-y-top`	`-50%`
`--magic-tray-handle-offset-y-right`	`0%`
`--magic-tray-handle-offset-y-bottom`	`50%`
`--magic-tray-handle-offset-y-left`	`0%`
`--magic-tray-handle-cursor`	`grab`
`--magic-tray-handle-cursor-dragging`	`grabbing`
`--magic-tray-handle-z-index`	`1`

MagicTrayTransform

Translates a nested layer alongside the clip. As an edge is dragged inward, the wrapped content is pushed away from that edge by the same distance, while a background layer stays anchored.

Props

Prop	Type	Default
`axis`	`MagicTrayTransformAxis`	`'both'`
`factor`	`number`	`1`
`disabled`	`boolean`	`false`

MagicTray

A self-contained component that composes the provider and content internally. Use this for simple, inline cases where you don’t need custom markup.

Props

Prop	Type	Required
`id`	`MaybeRef<string>`	`true`
`options`	`MagicTrayOptions`	`false`

Slots

Slot	Description
`default`	The content that gets clipped.
`background`	A layer that fills the full content element, including the reserved overshoot padding.
`handle`	Custom handle visuals. Rendered once per draggable side and scoped with the respective `side`.

useMagicTray

The composable returns the tray’s reactive state and a set of functions to control it programmatically.

Property	Type	Description
`progress`	`Ref<Record<MagicTraySide, number>>`	Per side inset progress, 0 (open) to 1 (fully clipped).
`activeSnapPoint`	`Ref<Partial<Record<MagicTraySide, MagicTraySnapPoint>>>`	The snap point each side is currently snapped to.
`snapTo`	`(side, snapPoint, duration?) => void`	Snap a single side to a snap point, optionally overriding the animation duration.

Events

The tray emits the following events through MagicEmitter. Listen to them with useMagicEmitter.

Event	Payload	Description
`beforeDrag`	`{ id, side, value }`	Fired when a side starts being dragged.
`drag`	`{ id, side, value }`	Fired continuously while a side is dragged. `value` is the current inset in pixels.
`afterDrag`	`{ id, side, value }`	Fired when a side stops being dragged.
`beforeSnap`	`{ id, snapPoint: { side, point } }`	Fired before a side animates to a snap point.
`snapTo`	`{ id, snapPoint: { side, point }, duration? }`	Fired when a side is asked to snap programmatically.
`afterSnap`	`{ id, snapPoint: { side, point } }`	Fired after a side has settled on a snap point.
`progress`	`{ id, side, value }`	Fired whenever a side’s inset progress changes. `value` is between 0 and 1.
`magnet`	`{ id, side, value }`	Fired whenever a magnetic pull changes, e.g. to drive a parallax in the handle slot. `value` is the pull as a fraction of `magnetism.pull`, signed by direction: positive when pulled inward, negative when pulled outward, 0 at rest.
`willSnapTo`	`{ id, side, snapPoint }`	Fired during a drag when the committed snap target changes — i.e. the snap point the edge will animate to on release. Only fires when the target actually changes, not on every move.

Errors

Source	Error Code	Message
`MagicTrayContent`	`missing_instance_id`	MagicTrayContent must be nested inside MagicTrayProvider
`MagicTrayTransform`	`missing_instance_id`	MagicTrayTransform must be nested inside MagicTrayProvider

Caveats

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

Examples

Combined Sides

PreviewCode

Drag any edge

<template>
  <magic-tray
    id="magic-tray-combined-demo"
    :options="{
      snapPoints: {
        top: [0, 0.2, 0.4],
        right: [0, 0.2, 0.4],
        bottom: [0, 0.2, 0.4],
        left: [0, 0.2, 0.4],
      },
      threshold: {
        distance: 32,
      },
    }"
    style="--magic-tray-radius: 0.75rem"
  >
    <template #background>
      <div class="bg-surface-base h-full w-full" />
    </template>
    <div
      class="flex aspect-16/9 w-120 max-w-full items-center justify-center select-none"
    >
      <span>Drag any edge</span>
    </div>
  </magic-tray>
</template>

Transform

Translate a layer alongside the clip with MagicTrayTransform, pushing content away from each edge as it is dragged in.

PreviewCode

Drag the right or bottom edge

<template>
  <magic-tray
    id="magic-tray-transform-demo"
    :options="{
      snapPoints: {
        right: [0, 0.25, 0.5],
        bottom: [0, 0.25, 0.5],
      },
      threshold: { distance: 32 },
    }"
    style="--magic-tray-radius: 0.75rem"
  >
    <template #background>
      <div class="bg-surface-base h-full w-full" />
    </template>
    <magic-tray-transform :factor="0.5">
      <div
        class="flex aspect-16/9 w-120 max-w-full flex-col items-center justify-center gap-8 p-8 select-none"
      >
        <p class="text-surface max-w-xs text-center">
          Drag the right or bottom edge
        </p>
      </div>
    </magic-tray-transform>
  </magic-tray>
</template>

Reveal

A composed tray layered over its own container, easing into its initial snap points on mount via initial.transition.

PreviewCode

Drag left or right edge

<template>
  <div
    class="bg-surface-low text-surface-subtle relative flex aspect-16/9 w-120 max-w-full items-center justify-between rounded-[0.25rem] select-none"
  >
    <span class="w-16 text-center">L</span>
    <span class="w-16 text-center">R</span>
    <magic-tray-provider :id="id" :options="options">
      <magic-tray-content
        :style="{
          '--magic-tray-radius': radius,
          '--magic-tray-drag-overshoot-outer': '3.5rem',
        }"
      >
        <template #background>
          <div class="bg-surface-base h-full w-full" />
        </template>
        <div
          class="text-surface flex h-full w-full items-center justify-center p-8 text-center"
        >
          Drag left or right edge
        </div>
      </magic-tray-content>
    </magic-tray-provider>
  </div>
</template>

<script lang="ts" setup>
import { computed } from 'vue'
import { useMagicTray } from '@maas/vue-equipment/plugins/MagicTray'
import type {
  MagicTrayOptions,
  MagicTraySide,
} from '@maas/vue-equipment/plugins/MagicTray'

const id = 'magic-tray-reveal-demo'
const sides: MagicTraySide[] = ['top', 'right', 'bottom', 'left']

const options: MagicTrayOptions = {
  snapPoints: {
    top: ['8px'],
    right: ['64px', '128px'],
    bottom: ['8px'],
    left: ['64px', '128px'],
  },
  initial: {
    snapPoints: { top: '8px', right: '64px', bottom: '8px', left: '64px' },
    transition: true,
  },
  threshold: { distance: 32 },
  inset: true,
}

const { state } = useMagicTray(id, options)

// Roundedness tracks the first 8px of clip, maxing out at 0.5rem
const radius = computed(() => {
  const clip = (side: MagicTraySide) =>
    Math.max(0, state.dragged[side] - state.overshoot.outer[side])
  const peek = Math.max(...sides.map(clip))
  return `${Math.min(1, peek / 8) * 0.5}rem`
})
</script>

Step Snapping

With snap.mode set to 'step', the edge advances to the adjacent snap point on each drag instead of jumping to the closest one, moving through the configured points one at a time.

PreviewCode

Drag the bottom edge

<template>
  <magic-tray
    id="magic-tray-step-snap-demo"
    :options="{
      snapPoints: { bottom: [0, 0.25, 0.5, 0.75, 1] },
      snap: { mode: 'step' },
      threshold: { distance: 32 },
    }"
    style="--magic-tray-radius: 0.5rem"
  >
    <template #background>
      <div class="bg-surface-base h-full w-full" />
    </template>
    <div
      class="flex aspect-16/9 w-120 max-w-full items-center justify-center select-none"
    >
      <span>Drag the bottom edge</span>
    </div>
  </magic-tray>
</template>

Drag Mode

With drag.mode set to 'snap', the edge commits straight to the snap point closest to the pointer while dragging. The cut is immediate, with no animation, and ignores snap.mode.

PreviewCode

Drag the bottom edge

<template>
  <magic-tray
    id="magic-tray-drag-mode-demo"
    :options="{
      snapPoints: { bottom: [0, 0.25, 0.5, 0.75, 1] },
      drag: { mode: 'snap' },
    }"
    style="--magic-tray-radius: 0.5rem"
  >
    <template #background>
      <div class="bg-surface-base h-full w-full" />
    </template>
    <div
      class="flex aspect-16/9 w-120 max-w-full items-center justify-center select-none"
    >
      <span>Drag the bottom edge</span>
    </div>
  </magic-tray>
</template>

Will Snap To

The willSnapTo event fires during a drag whenever the committed snap target changes — the snap point the edge will animate to on release. It only fires when the target changes, not on every move.

PreviewCode

Drag the left or right edge

snap points

left

0.25

0.5

0.75

right

0.75

0.5

0.25

willSnapTo events

—

<template>
  <div class="flex flex-col items-center gap-4 select-none">
    <div
      class="bg-surface-low text-surface-subtle relative flex aspect-16/9 w-120 max-w-full items-center justify-between overflow-hidden rounded-[0.25rem]"
    >
      <span class="w-16 text-center">L</span>
      <span class="w-16 text-center">R</span>
      <magic-tray-provider :id="id" :options="options">
        <magic-tray-content
          :style="{
            '--magic-tray-radius': '0.5rem',
            '--magic-tray-drag-overshoot-outer': '3.5rem',
          }"
        >
          <template #background>
            <div class="bg-surface-base h-full w-full" />
          </template>
          <div
            class="text-surface flex h-full w-full items-center justify-center p-8 text-center"
          >
            Drag the left or right edge
          </div>
        </magic-tray-content>
      </magic-tray-provider>
    </div>

    <div
      class="bg-surface-low text-surface w-120 max-w-full rounded-[0.25rem] p-4 font-mono text-sm"
    >
      <div class="text-surface-subtle mb-3 text-xs tracking-widest uppercase">
        snap points
      </div>
      <div class="mb-4 flex flex-col gap-3">
        <div
          v-for="side in ['left', 'right']"
          :key="side"
          class="flex items-center gap-3"
        >
          <span class="text-surface-subtle w-8 text-xs">{{ side }}</span>
          <div class="flex flex-1 justify-between">
            <div
              v-for="point in side === 'right'
                ? [...snapPointKeys].reverse()
                : snapPointKeys"
              :key="point"
              class="flex flex-col items-center gap-2"
            >
              <div
                class="h-2 w-2 rounded-full"
                :class="dotClass(side, point)"
              />
              <span class="text-surface-subtle text-xs">{{ point }}</span>
            </div>
          </div>
        </div>
      </div>

      <div class="text-surface-subtle mb-2 text-xs tracking-widest uppercase">
        willSnapTo events
      </div>
      <div class="flex flex-col gap-1.5">
        <template v-if="log.length">
          <div
            v-for="(entry, i) in log"
            :key="i"
            class="flex justify-between"
            :class="i === 0 ? 'text-surface' : 'text-surface-subtle'"
          >
            <span>
              <span class="opacity-50">{{ entry.side }}</span>
              {{ entry.snapPoint }}
            </span>
            <span>{{ directionArrow(entry.side, entry.snapPoint) }}</span>
          </div>
        </template>
        <span v-else class="text-surface-subtle">—</span>
      </div>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { ref, reactive, onBeforeUnmount } from 'vue'
import { useMagicTray } from '@maas/vue-equipment/plugins/MagicTray'
import { useMagicEmitter } from '@maas/vue-equipment/plugins/MagicEmitter'
import type { MagicEmitterEvents } from '@maas/vue-equipment/plugins/MagicEmitter'
import type {
  MagicTrayOptions,
  MagicTraySnapPoint,
  MagicTraySnapPointPayload,
  MagicTrayWillSnapToPayload,
} from '@maas/vue-equipment/plugins/MagicTray'

const id = 'magic-tray-will-snap-to-demo'
const snapPointKeys = [0, 0.25, 0.5, 0.75, 1]

const options: MagicTrayOptions = {
  snapPoints: {
    left: snapPointKeys,
    right: snapPointKeys,
  },
  threshold: { distance: 32 },
  inset: true,
}

const { activeSnapPoint } = useMagicTray(id, options)

const emitter = useMagicEmitter()

// The pending snap target per side during drag — null when not dragging
const willSnapTo = reactive<Record<string, MagicTraySnapPoint | null>>({
  left: null,
  right: null,
})

function dotClass(side: string, point: number) {
  if (willSnapTo[side] === point) {
    return 'bg-warning-solid'
  }
  if (
    (activeSnapPoint.value as Record<string, MagicTraySnapPoint | undefined>)[
      side
    ] === point
  ) {
    return 'bg-success-solid'
  }
  return 'bg-surface-base'
}

// Arrow reflects the spatial direction on screen
function directionArrow(side: string, snapPoint: MagicTraySnapPoint) {
  const p = Number(snapPoint)
  return side === 'right' ? (p === 0 ? '→' : '←') : p === 0 ? '←' : '→'
}

const log = ref<MagicTrayWillSnapToPayload[]>([])

// willSnapTo is shared across plugins, so the payload is a union — narrow it
// to this plugin’s shape via the side field before use
function onWillSnapTo(payload: MagicEmitterEvents['willSnapTo']) {
  if (payload.id !== id || !('side' in payload)) {
    return
  }
  willSnapTo[payload.side] = payload.snapPoint
  log.value.unshift(payload)
  if (log.value.length > 5) {
    log.value.length = 5
  }
}

function isTraySnapPointPayload(v: unknown): v is MagicTraySnapPointPayload {
  return typeof v === 'object' && v !== null && 'side' in v && 'point' in v
}

function onAfterSnap(payload: { id: string; snapPoint: unknown }) {
  if (payload.id !== id) {
    return
  }
  if (isTraySnapPointPayload(payload.snapPoint)) {
    willSnapTo[payload.snapPoint.side] = null
  }
}

emitter.on('willSnapTo', onWillSnapTo)
emitter.on('afterSnap', onAfterSnap)

onBeforeUnmount(() => {
  emitter.off('willSnapTo', onWillSnapTo)
  emitter.off('afterSnap', onAfterSnap)
})
</script>

Handle Click

A handle passes clicks through to its slotted content, so a clickable element inside a handle slot works as expected.

PreviewCode

Click a handle button to toggle
or drag to move freely

<template>
  <div class="flex flex-col items-center gap-4 select-none">
    <div
      class="bg-surface-low text-surface-subtle relative flex aspect-16/9 w-120 max-w-full items-center justify-between overflow-hidden rounded-[0.25rem]"
    >
      <span class="w-16 text-center">L</span>
      <span class="w-16 text-center">R</span>
      <magic-tray-provider :id="id" :options="options">
        <magic-tray-content :style="{ '--magic-tray-radius': '0.5rem' }">
          <template #background>
            <div class="bg-surface-base h-full w-full" />
          </template>
          <template #handle="{ side }">
            <button class="bg-surface h-full w-full" @click="toggle(side)" />
          </template>
          <div
            class="text-surface flex h-full w-full items-center justify-center p-8 text-center"
          >
            Click a handle button to toggle <br />
            or drag to move freely
          </div>
        </magic-tray-content>
      </magic-tray-provider>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { useMagicTray } from '@maas/vue-equipment/plugins/MagicTray'
import type {
  MagicTrayOptions,
  MagicTraySide,
} from '@maas/vue-equipment/plugins/MagicTray'

const id = 'magic-tray-handle-click-demo'

const options: MagicTrayOptions = {
  snapPoints: { left: [0, 0.25], right: [0, 0.25] },
  threshold: { distance: 32 },
  inset: true,
}

const { snapTo, activeSnapPoint } = useMagicTray(id, options)

// Toggle the side between its open and closed snap points on a genuine tap.
// A drag suppresses the click, so the handle still moves freely.
function toggle(side: MagicTraySide) {
  const current = activeSnapPoint.value[side]
  snapTo(side, current === 0 ? 0.25 : 0)
}
</script>

Magnetic

With magnetism.sides, an edge is pulled toward the cursor as it nears the handle, gaining as it closes in. Each snap point sets its direction: 'inner' pulls in from inside, 'outer' out from outside, 'both' from either side.

TIP

If you move the handle with --magic-tray-handle-offset-*, set magnetism.radius and magnetism.pull manually. Left at their defaults they derive from the handle’s position.

PreviewCode

Move toward the right edge

<template>
  <div
    class="bg-surface-low text-surface-subtle relative flex aspect-16/9 w-120 max-w-full items-center justify-between overflow-hidden rounded-[0.25rem] select-none"
  >
    <span class="w-16 text-center">L</span>
    <span class="w-16 text-center">R</span>
    <magic-tray-provider :id="id" :options="options">
      <magic-tray-content
        :style="{
          '--magic-tray-radius': '0.5rem',
          '--magic-tray-drag-overshoot-outer': '3.5rem',
          '--magic-tray-handle-width-y': '256px',
        }"
      >
        <template #background>
          <div class="bg-surface-base h-full w-full" />
        </template>
        <div
          class="text-surface flex h-full w-full items-center justify-center p-8 text-center"
        >
          Move toward the right edge
        </div>
      </magic-tray-content>
    </magic-tray-provider>
  </div>
</template>

<script lang="ts" setup>
import { useMagicTray } from '@maas/vue-equipment/plugins/MagicTray'
import type { MagicTrayOptions } from '@maas/vue-equipment/plugins/MagicTray'

const id = 'magic-tray-magnetic-demo'

const options: MagicTrayOptions = {
  snapPoints: {
    right: [0, 0.5, 1],
  },
  snap: { mode: 'step' },
  magnetism: {
    sides: {
      right: { 0: 'inner', 0.5: 'both', 1: 'outer' },
    },
  },
  threshold: { distance: 24 },
  inset: true,
}

useMagicTray(id, options)
</script>

Virtual Magnetism

With magnetism.virtual set to true, magnetism is still calucalted, but the clip path and handle stay put. The magnet event still fires, so you can drive custom effects such as transforms or parallax.

PreviewCode

Move toward the left or right edge
[clip stays frozen]

magnet event

left 0.000 right 0.000

state

activeSnapPoint.left—

progress.left0.000

activeSnapPoint.right—

progress.right0.000

<template>
  <div class="flex flex-col items-center gap-4 select-none">
    <div
      class="bg-surface-low text-surface-subtle relative flex aspect-16/9 w-120 max-w-full items-center justify-between overflow-hidden rounded-[0.25rem]"
    >
      <magic-tray-provider :id="id" :options="options">
        <magic-tray-content
          :style="{
            '--magic-tray-radius': '0.25rem',
            '--magic-tray-drag-overshoot-outer': '3.5rem',
            '--magic-tray-handle-offset-x-left': 'calc(-50% + 0.5rem)',
            '--magic-tray-handle-offset-x-right': 'calc(50% - 0.5rem)',
          }"
        >
          <template #handle-left>
            <div
              class="h-[calc(2.5rem+var(--handle-v,0)*1rem)] w-1 rounded-full bg-[#fff] opacity-[calc(0.1+var(--handle-v,0)*0.9)]"
              :style="{ '--handle-v': handleV('left') }"
            />
          </template>
          <template #handle-right>
            <div
              class="h-[calc(2.5rem+var(--handle-v,0)*1rem)] w-1 rounded-full bg-[#fff] opacity-[calc(0.1+var(--handle-v,0)*0.9)]"
              :style="{ '--handle-v': handleV('right') }"
            />
          </template>
          <template #background>
            <div class="bg-surface-base h-full w-full" />
          </template>
          <div
            class="text-surface flex h-full w-full items-center justify-center p-8 text-center"
          >
            Move toward the left or right edge<br />
            [clip stays frozen]
          </div>
        </magic-tray-content>
      </magic-tray-provider>
    </div>

    <div
      class="bg-surface-low text-surface w-120 max-w-full rounded-[0.25rem] p-4 font-mono text-sm"
    >
      <div class="text-surface-subtle mb-3 text-xs tracking-widest uppercase">
        magnet event
      </div>
      <div class="mb-1.5 flex justify-between text-xs">
        <span class="text-surface-subtle">
          left
          <span class="text-surface">{{ magnetValues.left.toFixed(3) }}</span>
        </span>
        <span class="text-surface-subtle">
          right
          <span class="text-surface">{{ magnetValues.right.toFixed(3) }}</span>
        </span>
      </div>
      <div class="bg-surface-base relative h-1 overflow-hidden rounded-full">
        <div
          class="bg-success-solid absolute right-1/2 h-full w-[calc(var(--bar-v,0)*50%)] opacity-(--bar-v,0)"
          :style="{ '--bar-v': magnetValues.left }"
        />
        <div
          class="bg-success-solid absolute left-1/2 h-full w-[calc(var(--bar-v,0)*50%)] opacity-(--bar-v,0)"
          :style="{ '--bar-v': magnetValues.right }"
        />
        <div
          class="bg-surface-subtle absolute top-0 left-1/2 h-full w-px -translate-x-1/2"
        />
      </div>

      <div
        class="text-surface-subtle mt-4 mb-3 text-xs tracking-widest uppercase"
      >
        state
      </div>
      <div class="flex flex-col gap-1.5">
        <template v-for="side in sides" :key="side">
          <div class="flex justify-between">
            <span class="text-surface-subtle">activeSnapPoint.{{ side }}</span>
            <span>{{ state.activeSnapPoint[side] ?? '—' }}</span>
          </div>
          <div class="flex justify-between">
            <span class="text-surface-subtle">progress.{{ side }}</span>
            <span>{{ state.progress[side].toFixed(3) }}</span>
          </div>
        </template>
      </div>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { reactive, onBeforeUnmount } from 'vue'
import { useMagicTray } from '@maas/vue-equipment/plugins/MagicTray'
import { useMagicEmitter } from '@maas/vue-equipment/plugins/MagicEmitter'
import type {
  MagicTrayOptions,
  MagicTraySide,
} from '@maas/vue-equipment/plugins/MagicTray'

const id = 'magic-tray-virtual-magnetic-demo'
const sides: MagicTraySide[] = ['left', 'right']

const options: MagicTrayOptions = {
  snapPoints: {
    left: [0, 0.25],
    right: [0, 0.25],
  },
  snap: { mode: 'step' },
  magnetism: {
    sides: {
      left: { 0: 'inner', 0.25: 'inner' },
      right: { 0: 'inner', 0.25: 'inner' },
    },
    radius: { start: 32, stop: 8 },
    virtual: true,
  },
  threshold: { distance: 32 },
  inset: true,
}

const { state } = useMagicTray(id, options)
const emitter = useMagicEmitter()

const magnetValues = reactive<Record<MagicTraySide, number>>({
  top: 0,
  right: 0,
  bottom: 0,
  left: 0,
})

function handleV(side: MagicTraySide) {
  return state.draggingSide === side ? 1 : magnetValues[side]
}

function onMagnet(payload: { id: string; side: MagicTraySide; value: number }) {
  if (payload.id === id) {
    magnetValues[payload.side] = payload.value
  }
}

emitter.on('magnet', onMagnet)

onBeforeUnmount(() => {
  emitter.off('magnet', onMagnet)
})
</script>

MagicTray ​

Overview ​

Anatomy ​

Simple ​

Composed ​

Installation ​

CLI ​

Vue ​

Nuxt ​

Direct Import ​

Composable ​

Peer Dependencies ​

Installation ​

API Reference ​

MagicTrayProvider ​

Props ​

Options ​

MagicTrayContent ​

Slots ​

CSS Variables ​

MagicTrayHandle ​

Slot Props ​

CSS Variables ​

MagicTrayTransform ​

Props ​

MagicTray ​

Props ​

Slots ​

useMagicTray ​

Events ​

Errors ​

Caveats ​

Examples ​

Combined Sides ​

Transform ​

Reveal ​

Step Snapping ​

Drag Mode ​

Will Snap To ​

Handle Click ​

Magnetic ​

Virtual Magnetism ​

MagicTray

Overview

Anatomy

Simple

Composed

Installation

CLI

Vue

Nuxt

Direct Import

Composable

Peer Dependencies

Installation

API Reference

MagicTrayProvider

Props

Options

MagicTrayContent

Slots

CSS Variables

MagicTrayHandle

Slot Props

CSS Variables

MagicTrayTransform

Props

MagicTray

Props

Slots

useMagicTray

Events

Errors

Caveats

Examples

Combined Sides

Transform

Reveal

Step Snapping

Drag Mode

Will Snap To

Handle Click

Magnetic

Virtual Magnetism