IToaster ​

Transient notifications, raised from anywhere — including plain functions outside a component's setup.

Mount one <IToaster /> in the app, typically just inside <IApp>, then call useToast() wherever you need it. This site mounts one, so every button below raises a real toast.

<script setup lang="ts">
import { useToast } from 'iryx-ui'

const { toast } = useToast()
</script>

<template>
  <IButton variant="outline" @click="toast('Draft saved')">
    Save
  </IButton>
</template>

A string is shorthand for { title }. Pass an object for anything more.

Variants ​

Five of them, with the colour in the icon rather than the surface, as in IAlert and IBadge.

toast({ title: 'Draft saved', variant: 'neutral' })
success({ title: 'Invoice sent', description: 'INV-1042 went to billing@example.com' })
warning({ title: 'Payment overdue', description: 'Three invoices passed their due date.' })
danger({ title: 'Upload failed', description: 'The connection dropped before the file finished.' })
info({ title: 'New version available', description: 'Reload to pick up 1.4.0.' })

success(…) and friends are shorthand for toast({ …, variant }), so anything the base call takes works on them too.

Duration ​

duration is milliseconds before the toast dismisses itself, falling back to the IToaster's own duration (5000 by default). 0 keeps it open until dismissed.

toast({ title: 'Gone in a second', duration: 1000 })
danger({ title: 'Upload failed', duration: 0 })

Actions ​

An action puts one button in the toast. A toast leaves on its own, so keep it to undo-shaped offers and put anything the reader must do in a dialog.

toast({
  title: 'Invoice deleted',
  description: 'INV-1042 moved to the archive.',
  action: { label: 'Undo', onClick: () => restore(invoice) },
})

Promises ​

promise() covers a piece of async work with one toast: a spinner while it runs, then the success or error message in the same place. The spinner stays until the promise settles; the result then dismisses on the usual duration.

const { promise } = useToast()

promise(sendInvoice(invoice), {
  loading: 'Sending invoice…',
  success: sent => `${sent.number} sent`,
  error: error => ({ title: 'Could not send the invoice', description: error.message }),
})

Each message takes the same string or options object as toast(), or a function of the resolved value or the error. promise() returns the toast's id, not the result, so await your own promise for that. Dismissing the toast while the work runs keeps it dismissed.

Dismissing from code ​

toast() returns an id, so a toast raised while work is in flight can be taken down when the work finishes.

const id = toast({ title: 'Uploading…', duration: 0 })
await upload(file)
dismiss(id)
success('Upload complete')

Position ​

Six viewport positions, set once on the IToaster. Individual toasts do not choose their own.

<IApp>
  <RouterView />
  <IToaster position="bottom-right" />
</IApp>

The API ​

const { toast, success, warning, danger, info, dismiss, clear } = useToast()

toast(options) // returns a number: the toast's id
success(options)
warning(options)
danger(options)
info(options)
update(id, options) // replace an open toast's content
promise(work, { loading, success, error }) // returns the toast's id
dismiss(id)
clear()

options is a string — shorthand for the title — or:

interface ToastOptions {
  title?: string
  description?: string
  variant?: 'neutral' | 'success' | 'warning' | 'danger' | 'info' | 'loading'
  /** Milliseconds before auto-dismiss. `0` keeps it until dismissed. */
  duration?: number
  action?: {
    label: string
    onClick: () => void
  }
}

The store behind it is a module-level singleton, so toast() can be called from a plain function with no component in scope.

Props ​

Mount exactly one. Two toasters render the same store twice, so every toast appears twice.