Toast
Show temporary notifications with optional actions.
Demos
Use 0 for persistent notifications. Hover or focus to pause. Press F8 to inspect the stack.
Usage
<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.
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.
<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/.
<script setup lang="ts">
import { AppLayout as Primitive } from 'akaza-ui'
import { computed, useAttrs, useTemplateRef } from 'vue'
import { cn } from '../../../utils/ui'
import uiConfig from '../ui.config'
import {
appLayoutVariants,
resolveAppLayoutVariants,
type AppLayoutProps,
type AppLayoutSlots,
} from './index'
defineOptions({ inheritAttrs: false })
// Preserve Akaza defaults when optional props, including Boolean aliases, are omitted.
const props = withDefaults(defineProps<AppLayoutProps>(), {
as: undefined,
mainAs: undefined,
layout: undefined,
scroll: undefined,
viewport: undefined,
stickyHeader: undefined,
stickyFooter: undefined,
stickySides: undefined,
stickyLeft: undefined,
stickyRight: undefined,
safeArea: undefined,
mainId: undefined,
mainLabel: undefined,
skipLink: undefined,
skipLabel: undefined,
ui: undefined,
})
defineSlots<AppLayoutSlots>()
const attrs = useAttrs()
const styles = computed(() => appLayoutVariants(resolveAppLayoutVariants(props, uiConfig)))
const mergedUi = computed(() => {
const overrides = props.ui as Record<string, string | undefined> | undefined
return Object.fromEntries(
Object.entries(styles.value).map(([part, style]) => [
part,
cn(style(), overrides?.[part], part === 'root' ? props.class : undefined),
]),
)
})
const primitiveProps = computed(() => {
const { class: _class, ui: _ui, ...native } = props
return native
})
const primitive = useTemplateRef<InstanceType<typeof Primitive>>('primitive')
defineExpose({
get main() {
return primitive.value!.main
},
get focusMain() {
return primitive.value!.focusMain
},
})
</script>
<template>
<component
:is="Primitive"
ref="primitive"
v-bind="{ ...primitiveProps, ...attrs }"
:ui="mergedUi"
>
<template v-for="(_, name) in $slots" #[name]="scope"
><slot :name="name as keyof AppLayoutSlots" v-bind="scope ?? {}"
/></template>
</component>
</template>
API
Variants and defaults
| Prop | Values | Default |
|---|---|---|
size | xs, sm, md, lg, xl | sm |
Props
| Prop | Default | Purpose |
|---|---|---|
position | bottom-right | top-left, top-center, top-right, bottom-left, bottom-center, or bottom-right. |
limit | 3 | Maximum interactive cards. Older entries stay mounted but hidden and inert. |
stack | true | Collapse cards until hover or focus. |
gap | 12 | Expanded gap in pixels. |
peek | 12 | Visible edge of each collapsed card. |
scaleStep | 0.1 | Scale reduction for cards behind the newest one. |
pauseOnHover | true | Pause dismissal while inspecting a card. |
pauseOnFocus | true | Pause dismissal while using keyboard controls. |
pauseOnWindowBlur | true | Pause while the window is inactive. |
hotkey | ['F8'] | Focus and expand the notification viewport. |
hotkeyLabel | Notifications | Accessible name for the viewport. |
closeLabel | Dismiss notification | Accessible name for close controls. |
swipeDirection | Inferred from position | Dismiss toward the viewport edge. |
swipeThreshold | 50 | Required swipe distance in pixels. |
teleport | body | Viewport target; false renders inline. |
manager | Injected manager | Use 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
| Slot | Props | Description |
|---|---|---|
toast | toast, type, priority, action, attrs, close, performAction | Complete inner content override with direct metadata and built-in action lifecycle. |
title | toast | Title content. |
description | toast | Description content. |
close | toast | Close-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
| Event | Payload | Description |
|---|---|---|
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
| Key | Behavior |
|---|---|
F8 | Focuses and expands viewport by default. |
Tab | Moves through toast actions and close buttons. |
Escape | Closes latest toast while focus is inside viewport. |