Toast · juxt.ui

Installation #

With the Nuxt module, every component and composable is auto-imported — there is nothing to add. In a plain Vue project, import what you use:

import { JToaster, toast } from '@juxtui/ui'

Usage #

<!-- once, e.g. in app.vue -->
<JToaster />

<script setup lang="ts">
import { toast } from '@juxtui/ui'

toast.success('Changes saved')
</script>

toast() works anywhere — in components, stores or plain functions. In Nuxt it is auto-imported.

Timers pause while the pointer is over the stack, while a toast has focus, and while the tab is hidden. The hairline at the bottom shows the time left.

On touch screens, swipe a toast sideways to dismiss it.

Variants & examples #

With an action#

Offer undo instead of asking for confirmation.

<script setup lang="ts">
function archive() {
  toast('Conversation archived', {
    action: { label: 'Undo', onClick: () => toast.success('Restored') },
  })
}
</script>

<template>
  <JButton variant="outline" @click="archive">Archive conversation</JButton>
</template>

Following a promise#

One toast moves from loading to success or error.

<script setup lang="ts">
function deploy() {
  const work = new Promise<string>((resolve, reject) => {
    setTimeout(() => (Math.random() > 0.25 ? resolve('juxt.dev') : reject(new Error('Timeout'))), 1800)
  })
  toast.promise(work, {
    loading: 'Deploying…',
    success: url => `Live on ${url}`,
    error: 'Deployment failed',
  }).catch(() => {})
}
</script>

<template>
  <JButton @click="deploy">Deploy</JButton>
</template>

API #

JToaster

Prop	Type	Default	Description
position	`'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'`	`'bottom-right'`	Where the stack sits. Full width on small screens.
max	`number`	`4`	Visible at once. Extra toasts wait their turn.
hotkey	`string`	`'alt+t'`	Moves focus to the newest toast.
label	`string`	`'Notifications'`	Accessible name of the region.

toast()

Prop	Type	Default	Description
description	`string`	—	Secondary line.
type	`'default' \| 'success' \| 'error' \| 'warning' \| 'info' \| 'loading'`	`'default'`	Icon and emphasis.
duration	`number`	`5000`	In ms; errors get 2s more. `Infinity` keeps it open.
action	`{ label, onClick }`	—	A single action button.
dismissible	`boolean`	`true`	Show the close button and allow Escape / swipe.
id	`string`	—	Reuse an id to replace a toast instead of stacking.
onDismiss	`() => void`	—	Called when the toast leaves.

Functions

Method	Signature	Description
toast(title, options?)	`string`	Show a toast. Returns its id.
toast.success / error / warning / info	`string`	Typed shortcuts.
toast.loading(title)	`string`	Stays until updated or dismissed.
toast.promise(promise, messages)	`Promise<T>`	`{ loading, success, error }` — messages can be functions of the result.
toast.update(id, patch)	`void`	Change a toast in place; its timer restarts.
toast.dismiss(id?)	`void`	Dismiss one toast, or all of them.

Accessibility #

Toasts are inserted into a persistent aria-live="polite" region, so they are announced reliably without interrupting.
Errors use role="alert" and are announced immediately.
Nothing auto-dismisses while it has focus or the pointer is over it.
Don’t put the only path to something important in a toast — it will go away.

Keyboard #

Key	Action
`AltT`	Focus the newest toast.
`Tab`	Move between toasts and their buttons.
`Esc`	Dismiss the focused toast.