MagicToast

MagicToast let’s you trigger and display toasts from anywhere.

PreviewCode

<template>
  <m-button @click="onClick">Add Toast</m-button>
  <magic-toast-provider id="magic-toast-demo" />
</template>

<script lang="ts" setup>
import { defineAsyncComponent, ref } from 'vue'
import { MButton } from '@maas/mirror/vue'
import { useMagicToast } from '@maas/vue-equipment/plugins/MagicToast'

const count = ref(0)

const component = defineAsyncComponent(
  () => import('./components/DemoToast.vue')
)
const { add } = useMagicToast('magic-toast-demo')

function onClick() {
  count.value += 1

  const props = {
    message: count.value % 2 ? 'Magic as a Service™' : 'Vue Equipment',
  }

  add({ component, props })
}
</script>

Overview

Anatomy

vue

<template>
  <magic-toast-provider id="your-toast-id" />
</template>

<script>
import { defineAsyncComponent } from 'vue'
import { useMagicToast } from '@maas/vue-equipment/plugins/MagicToast'

const component = defineAsyncComponent(() => import('./YourToast.vue'))
const { add } = useMagicToast('your-toast-id')

function handleClick() {
  add({ component })
}
</script>

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 MagicToastPlugin to your app.

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

const app = createApp({})

app.use(MagicToastPlugin)

Nuxt

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

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

Composable

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

const component = defineAsyncComponent(() => import('./YourToast.vue'))
const { add } = useMagicToast('your-toast-id')

function handleClick() {
  add({ component })
}

TIP

If you have installed the toaster 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

MagicToastProvider

The MagicToastProvider wraps the toaster and configures it according to the provided options.

Props

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

Options

Option	Type	Default
`debug`	`boolean`	`false`
`position`	`Position`	`bottom`
`duration`	`number`	`0`
`scrollLock`	`boolean \| object`	`object`
`scrollLock.padding`	`boolean`	`true`
`teleport.target`	`string`	`body`
`teleport.disabled`	`boolean`	`false`
`transition`	`string`	`magic-toast`
`layout.expand`	`string \| false`	`click`
`layout.max`	`number`	`3`
`animation.snap.duration`	`number`	`300`
`animation.snap.easing`	`function`	`—`
`initial.expanded`	`boolean`	`false`
`threshold.lock`	`number`	`8`
`threshold.distance`	`number`	`32`
`threshold.momentum`	`number`	`1`

CSS Variables

Variable	Default
`--magic-toast-padding-y`	`1rem`
`--magic-toast-padding-x`	`1rem`
`--magic-toast-gap`	`0.75rem`
`--magic-toast-animation-duration`	`175ms`
`--magic-toast-scale-factor`	`0.05`
`--magic-toast-overlap-y`	`1rem`
`--magic-toast-position`	`fixed`
`--magic-toast-inset`	`0`
`--magic-toast-width`	`100%`
`--magic-toast-height`	`100%`
`--magic-toast-z-index`	`999`

MagicToastView

MagicToastView is used internally. Some CSS is configurable.

Variable	Default
`--magic-toast-view-transition`	`all var(--magic-toast-animation-duration) var(--ease-in-out)`
`--magic-toast-view-cursor`	`grab`
`--magic-toast-view-cursor-dragging`	`grabbing`

Errors

Source	Error Code	Message
`MagicToastView`	`missing_instance_id`	`MagicToastView must be used within a MagicToastProvider`

Examples

Position

PreviewCode

Position

<template>
  <div class="w-full flex gap-2">
    <m-button @click="onClick">Add Toast</m-button>
    <m-select
      v-model="position"
      :options="options"
      label="Position"
      placeholder="Position"
    />
  </div>
  <magic-toast-provider
    id="magic-toast-position-demo"
    :options="{
      position,
    }"
  />
</template>

<script lang="ts" setup>
import { defineAsyncComponent, ref } from 'vue'
import { MButton, MSelect } from '@maas/mirror/vue'
import { useMagicToast } from '@maas/vue-equipment/plugins/MagicToast'

const component = defineAsyncComponent(
  () => import('./components/DemoToast.vue')
)
const { add } = useMagicToast('magic-toast-position-demo')

const position = ref('bottom-right')

const options = [
  { value: 'top-right', label: 'Top Right' },
  { value: 'top', label: 'Top' },
  { value: 'top-left', label: 'Top Left' },
  { value: 'left', label: 'Left' },
  { value: 'bottom-left', label: 'Bottom Left' },
  { value: 'bottom', label: 'Bottom' },
  { value: 'bottom-right', label: 'Bottom Right' },
  { value: 'right', label: 'Right' },
]

function onClick() {
  const props = {
    message: options.find((p) => p.value === position.value)?.label,
  }

  add({ component, props })
}
</script>

Expanded

PreviewCode

<template>
  <m-button @click="onClick">Add Toast</m-button>
  <magic-toast-provider id="magic-toast-expanded-demo" :options="options" />
</template>

<script lang="ts" setup>
import { defineAsyncComponent, ref } from 'vue'
import { MButton } from '@maas/mirror/vue'
import { useMagicToast } from '@maas/vue-equipment/plugins/MagicToast'

const count = ref(0)

const component = defineAsyncComponent(
  () => import('./components/DemoToast.vue')
)
const { add } = useMagicToast('magic-toast-expanded-demo')

function onClick() {
  count.value += 1

  const props = {
    message: count.value % 2 ? 'Magic as a Service™' : 'Vue Equipment',
  }

  add({ component, props })
}

const options = {
  layout: {
    expand: false,
  },
  initial: {
    expanded: true,
  },
}
</script>

Collapsed

PreviewCode

<template>
  <m-button @click="onClick">Add Toast</m-button>
  <magic-toast-provider id="magic-toast-collapsed-demo" :options="options" />
</template>

<script lang="ts" setup>
import { defineAsyncComponent, ref } from 'vue'
import { MButton } from '@maas/mirror/vue'
import { useMagicToast } from '@maas/vue-equipment/plugins/MagicToast'

const count = ref(0)

const component = defineAsyncComponent(
  () => import('./components/DemoToast.vue')
)
const { add } = useMagicToast('magic-toast-collapsed-demo')

function onClick() {
  count.value += 1

  const props = {
    message: count.value % 2 ? 'Magic as a Service™' : 'Vue Equipment',
  }

  add({ component, props })
}

const options = {
  layout: {
    expand: false,
  },
}
</script>

Hover

PreviewCode

<template>
  <m-button @click="onClick">Add Toast</m-button>
  <magic-toast-provider id="magic-toast-hover-demo" :options="options" />
</template>

<script lang="ts" setup>
import { defineAsyncComponent, ref } from 'vue'
import { MButton } from '@maas/mirror/vue'
import { useMagicToast } from '@maas/vue-equipment/plugins/MagicToast'

const count = ref(0)

const component = defineAsyncComponent(
  () => import('./components/DemoToast.vue')
)
const { add } = useMagicToast('magic-toast-hover-demo')

function onClick() {
  count.value += 1

  const props = {
    message: count.value % 2 ? 'Magic as a Service™' : 'Vue Equipment',
  }

  add({ component, props })
}

const options = {
  layout: {
    expand: 'hover',
  },
}
</script>

Clear All

PreviewCode

<template>
  <div class="flex gap-2">
    <m-button @click="onClick">Add Toast</m-button>
    <m-button @click="clear">Clear All</m-button>
  </div>
  <magic-toast-provider id="magic-toast-clear-all-demo" />
</template>

<script lang="ts" setup>
import { defineAsyncComponent, ref } from 'vue'
import { MButton } from '@maas/mirror/vue'
import { useMagicToast } from '@maas/vue-equipment/plugins/MagicToast'

const count = ref(0)

const component = defineAsyncComponent(
  () => import('./components/DemoToast.vue')
)
const { add, clear } = useMagicToast('magic-toast-clear-all-demo')

function onClick() {
  count.value += 1

  const props = {
    message: count.value % 2 ? 'Magic as a Service™' : 'Vue Equipment',
  }

  add({ component, props })
}
</script>

Slot

PreviewCode

<template>
  <m-button @click="onClick">Add Toast</m-button>
  <magic-toast-provider id="magic-toast-slot-demo" />
</template>

<script lang="ts" setup>
import { defineAsyncComponent, ref, h, type Slots } from 'vue'
import { MButton } from '@maas/mirror/vue'
import { useMagicToast } from '@maas/vue-equipment/plugins/MagicToast'

const count = ref(0)

const component = defineAsyncComponent(
  () => import('./components/DemoToast.vue')
)

const { add } = useMagicToast('magic-toast-slot-demo')

function onClick() {
  count.value += 1

  // Break reactivity for count
  const mappedCount = count.value

  const slots: Slots = {
    default: () => [h('span', `Message #${mappedCount}`)],
  }

  add({ component, slots })
}
</script>

Slotted Component

PreviewCode

<template>
  <m-button @click="onClick">Add Toast</m-button>
  <magic-toast-provider id="magic-toast-nested-slot-demo" />
</template>

<script lang="ts" setup>
import { defineAsyncComponent, ref, h, type Slots } from 'vue'
import { MButton } from '@maas/mirror/vue'
import { useMagicToast } from '@maas/vue-equipment/plugins/MagicToast'

const count = ref(0)

const component = defineAsyncComponent(
  () => import('./components/DemoToast.vue')
)

const slot = defineAsyncComponent(() => import('./components/DemoSlot.vue'))

const { add } = useMagicToast('magic-toast-nested-slot-demo')

function onClick() {
  count.value += 1

  // Break reactivity for count
  const mappedCount = count.value

  const slots: Slots = {
    default: () => [h(slot, { message: `Component #${mappedCount}` })],
  }

  add({ component, slots })
}
</script>

MagicToast ​

Overview ​

Anatomy ​

Installation ​

CLI ​

Vue ​

Nuxt ​

Composable ​

Peer Dependencies ​

Installation ​

API Reference ​

MagicToastProvider ​

Props ​

Options ​

CSS Variables ​

MagicToastView ​

Errors ​

Examples ​

Position ​

Expanded ​

Collapsed ​

Hover ​

Clear All ​

Slot ​

Slotted Component ​

MagicToast

Overview

Anatomy

Installation

CLI

Vue

Nuxt

Composable

Peer Dependencies

Installation

API Reference

MagicToastProvider

Props

Options

CSS Variables

MagicToastView

Errors

Examples

Position

Expanded

Collapsed

Hover

Clear All

Slot

Slotted Component