Toast

01Preview

Change the controls, then show a toast. It appears at the bottom-end of the window. Press F8 to move focus to the notifications region.

import { Button, ToastProvider, Toaster, useToast } from '@nuton/ui'

// Once, near the app root
<ToastProvider>
  <App />
  <Toaster />
</ToastProvider>

// Anywhere below it
const { toast } = useToast()

<Button onClick={() => toast({
  status: 'success',
  title: 'Lesson moved to Biology 101',
  description: 'Photosynthesis basics is now in Biology 101.',
})}>Move lesson</Button>

02Installation

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

import '@nuton/tokens/tokens.css'
import '@nuton/ui/styles.css'

Wrap the app once in ToastProvider and place one Toaster inside it. Toast reuses the Alert styles, which are part of styles.css.

import { ToastProvider, Toaster } from '@nuton/ui'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ToastProvider>
      {children}
      <Toaster />
    </ToastProvider>
  )
}

03Usage

import { useToast } from '@nuton/ui'

const { toast } = useToast()

toast({ status: 'success', title: 'Notes saved', description: 'Cell respiration notes are in Biology 101.' })

• Use a toast to confirm something people just did: saved, moved, copied, sent.
• Keep it short: a title of a few words and at most one sentence of description.
• Never put the only way to do something in a toast. It disappears, and screen-reader and keyboard users may not reach it in time. An Undo action must also exist elsewhere, named in altText.
• For information people must read or act on, use an Alert in the page or a Modal.

04Variants and sizes

Toast takes the same statuses, appearances and sizes as Alert (see the Alert matrix). It defaults to the stroke appearance; one-line when there is no description, large when there is. The floating shadow and motion are code-only.

Statuses

toast({ title: 'Link copied', description: 'Share it with your study group.' })
toast({ status: 'information', title: 'AI Tutor is updating', description: 'Answers may take a little longer for a few minutes.' })
toast({ status: 'success', title: 'Notes saved', description: 'Cell respiration notes are in Biology 101.' })
toast({ status: 'warning', title: 'You’re offline', description: 'Changes are kept on this device until you reconnect.' })
toast({ status: 'error', title: 'Upload failed', description: 'The file is larger than 50 MB.' })

05States and interactions

With reduced motion the toast appears and disappears without sliding or fading. A swipe still follows the finger.

State tokens

Toast uses the Alert tokens on .nu-alert (status, appearance and size) and adds --nu-toast-shadow on .nu-toast, and --nu-toast-width and --nu-toast-inset on .nu-toast-viewport.

06Composition examples

Undo after a delete

The lesson goes to Trash at once; the toast offers a shortcut to undo. altText tells screen-reader users where else to restore it.

toast({
  title: 'Lesson moved to Trash',
  description: lesson.name,
  action: { label: 'Undo', altText: 'Restore it from Trash', onClick: () => restore(lesson) },
})

Replace a toast

Pass the same id to update a toast in place, for example when an upload finishes.

const id = toast({ title: 'Uploading lecture-notes.pdf…', duration: 60000 })
// later
toast({ id, status: 'success', title: 'Upload complete', description: 'lecture-notes.pdf is in Biology 101.' })

07API reference

toast(options)

ToastProvider, Toaster and useToast

Accessibility

You must: keep toasts short, never make a toast the only way to reach an action, and give actions an altText that names the other way.

Figma mapping

08Guidelines and related components

Do and don't

Related components

• AlertThe same anatomy, inline in the page.
• ModalFor decisions that need an answer.
• Link buttonThe text button used for the toast action.