Toast

Transient messages that stack and dismiss themselves. A provider plus a useToast() hook rather than a global singleton, so the queue lives in React state and two regions can coexist.

src/components/ui/toast.tsx

About

From the component's own source, where it was written.

Transient messages that stack and dismiss themselves.

A provider plus a useToast() hook, rather than a global singleton: the queue lives in React state, so it participates in normal rendering and testing, and two independent regions can coexist.

The region is aria-live="polite" so a toast is announced without stealing focus — a toast that grabs focus interrupts whatever the user was typing.

Install

npx astralyx-ui add toast

Usage

import { ToastProvider, useToast } from '@/components/ui/toast'

// once, near the root
<ToastProvider position="bottom-end">{children}</ToastProvider>

// anywhere below it
const { toast } = useToast()
toast({ title: 'Saved', description: 'Your changes are live.', color: 'green' })

Composer

Change the props and the source below follows.

Props

position

color

duration

description

tsx

const { toast } = useToast()

toast({
  title: 'Deployment finished',
  description: 'Build 1482 is live on production.',
  color: 'neutral',
  duration: 4000,
})

Examples

Queue and stacking

tsx

const { toast } = useToast()
toast({ title: 'Deployment finished', color: 'green' })

API

Generated from the source, so it cannot fall behind the code. One table per exported component, then hooks, functions and types.

`ToastProvider`

Prop	Type	Default	Description
children	ReactNode	required	—
max	number	4	Oldest toasts fall off once this many are showing.
position	'top-end' \| 'top-start' \| 'bottom-end' \| 'bottom-start'	'bottom-end'	Corner the region is anchored to. Bottom positions stack upward.
id	(id: number) => void	—	Removes a toast early.

`Toast`

Extends Omit<ComponentProps<'div'>, 'title' | 'color'>.

Prop	Type	Default	Description
title	ReactNode	—	—
description	ReactNode	—	—
color	ColorSet	'neutral'	Tints the title.
duration	number	4000	Milliseconds before auto-dismiss. 0 keeps it until dismissed.
action	ReactNode	—	—
onDismiss	() => void	required	—
dismissLabel	string	'Dismiss'	Accessible name for the dismiss button.

Hooks

Hook	Signature	Description
useToast	() => ToastContextValue	—
useToastActions	() => ToastActions	The same two functions without the list. A component that only raises toasts should use this: `useToast` also returns `toasts`, so it re-renders every time one appears or leaves.

Types

`ToastOptions`

Transient messages that stack and dismiss themselves.

Field	Type	Description
title?	ReactNode	—
description?	ReactNode	—
color?	ColorSet	—
duration?	number	Milliseconds before auto-dismiss. `0` keeps it until dismissed.
action?	ReactNode	—

Behaviour

Topic	Detail	Description
toast(options)	(options) => number	Queues a toast and returns its id.