Skip to content

Toast

Show temporary notifications with optional actions.

Demos

Size
Simulate failure

Use 0 for persistent notifications. Hover or focus to pause. Press F8 to inspect the stack.

Usage

vue
<script setup lang="ts">
import { Accordion } from '~/components/ui/accordion'

const items = [
  { value: 'source', label: 'Do I own the source?', content: 'Yes. Copy and adapt the files.' },
]
</script>

<template>
  <Accordion :items="items" />
</template>

Mount one Toast viewport per manager near your application root. Call useToast() in component setup, then add notifications from event handlers. The preview uses its own queue so examples do not leave notifications on other pages.

Actions and updates

Use duration: 0 for a message that should stay until dismissed. Actions close after success. While an asynchronous action runs, its button shows progress and blocks repeated clicks. Rejected actions emit action-error and leave the toast open.

ts
const dialog = useOverlay().create(Dialog, {
  props: {
    title: 'Review changes',
    closeOnBackdropClick: false,
    duration: 180,
    width: 'sm',
  },
  destroyOnClose: true,
})

const { result } = dialog.open({ description: 'Check the changes before continuing.' })
dialog.patch({ title: 'Updated review', fullscreen: true })
dialog.close()
await result
dialog.unmount()

restoreProject is your application handler. For a request, use toast.promise() to update one notification as it settles. Add data: { pending: true } to show the loading icon, and clear that flag in the settled states.

ts
<Pagination v-model="page" :total="100" variant="solid" />
<Pagination v-model="page" :total="100" variant="outline" />

Handle request failures in the calling workflow. Reuse an id with toast.add() or toast.update() to change a notification without adding another queue entry.

Behavior

Toasts slide into a stack and support swipe dismissal. Movement takes 500ms, height changes take 150ms, and content fades take 250ms. Cards stack until hovered or focused, then expand with the configured gap. Timers pause on hover, focus, and window blur by default. Reduced motion removes transitions and spinner rotation.

Cards keep a neutral surface with a semantic status icon. Titles and descriptions wrap within their own column, separate from the close button. Long messages scroll within the card; the viewport stays 16px from the screen edges.

Installation

Complete the shared installation. Copy Toast.vue and index.ts into app/components/ui/toast/.

API

Variants and defaults

PropValuesDefault
sizexs, sm, md, lg, xlsm

Props

PropDefaultPurpose
positionbottom-righttop-left, top-center, top-right, bottom-left, bottom-center, or bottom-right.
limit3Maximum interactive cards. Older entries stay mounted but hidden and inert.
stacktrueCollapse cards until hover or focus.
gap12Expanded gap in pixels.
peek12Visible edge of each collapsed card.
scaleStep0.1Scale reduction for cards behind the newest one.
pauseOnHovertruePause dismissal while inspecting a card.
pauseOnFocustruePause dismissal while using keyboard controls.
pauseOnWindowBlurtruePause while the window is inactive.
hotkey['F8']Focus and expand the notification viewport.
hotkeyLabelNotificationsAccessible name for the viewport.
closeLabelDismiss notificationAccessible name for close controls.
swipeDirectionInferred from positionDismiss toward the viewport edge.
swipeThreshold50Required swipe distance in pixels.
teleportbodyViewport target; false renders inline.
managerInjected managerUse a separate notification queue.

Dismissal duration belongs to toast.add({ duration }), not the viewport. Visual type and announcement priority are independent: error and alert default to assertive announcements; other types are polite.

Slots

SlotPropsDescription
toasttoast, type, priority, action, attrs, close, performActionComplete inner content override with direct metadata and built-in action lifecycle.
titletoastTitle content.
descriptiontoastDescription content.
closetoastClose-button content.

The ui prop accepts the native viewport, toast, title, description, close, and action parts, plus IPEX layout, icon, and content parts. A custom toast slot replaces the default inner layout; the native root retains queue behavior and accessibility.

Events

EventPayloadDescription
action-error(error, toast)Action rejected or threw; toast remains open.
swipe-start(toast, event)Swipe interaction started.
swipe-move(toast, event)Pointer moved during swipe.
swipe-cancel(toast, event)Swipe ended below threshold or was canceled.
swipe-end(toast, event)Swipe crossed threshold and closed toast.

Keyboard

KeyBehavior
F8Focuses and expands viewport by default.
TabMoves through toast actions and close buttons.
EscapeCloses latest toast while focus is inside viewport.