Toast

A brief message that confirms an action or reports its result, then gets out of the way.

Import

import { Toast, useToastManager } from '@oztix/roadie-components/toast'

Setup

RoadieProvider mounts Toast.Provider and a Toast.Viewport at your app root, so toasts work once you've followed Installation. The viewport portals to the end of the page. Toasts stack at the bottom end of wide screens and span the bottom of small ones. See Position to change that.

<RoadieProvider link={NextLink} toast={{ position: 'top-end' }}>
  {children}
</RoadieProvider>

Placing providers yourself? Mount one Toast.Provider at the root with a Toast.Viewport inside it.

toast takes Toast.Provider's timeout (5000ms by default) and limit (3 on screen by default) for every toast in the app. This site mounts one, so the examples below work as they would in your app.

Examples

Default

Call useToastManager() in any component under the provider, then add a toast. A title on its own is often enough. A thin bar along the bottom shows how long the toast has left.

function CopyLink() {
  const toast = useToastManager()
  return (
    <Button onClick={() => toast.add({ title: 'Link copied' })}>
      <LinkSimpleIcon weight='bold' className='size-4' />
      Copy link
    </Button>
  )
}
render(<CopyLink />)

Intents

Pass intent to colour the toast and lead with a matching icon. Without one it stays neutral, with no icon.

function Intents() {
  const toast = useToastManager()
  const toasts = {
    success: ['Tickets sent', 'Check your inbox for 2 tickets.'],
    info: ['Doors open at 7pm', 'Arrive early for the support act.'],
    warning: ['Only 12 tickets left', 'Your cart is held for 10 minutes.'],
    danger: ['Card declined', 'Try another card or contact your bank.']
  }
  return (
    <div className='flex flex-wrap gap-2'>
      {Object.entries(toasts).map(([intent, [title, description]]) => (
        <Button
          key={intent}
          intent={intent}
          onClick={() => toast.add({ title, description, intent })}
        >
          {intent}
        </Button>
      ))}
    </div>
  )
}
render(<Intents />)

Position

Set position once for the whole app, in RoadieProvider's toast or on Toast.Viewport: bottom-end (the default), bottom-center, top-end or top-center. end follows the reading direction. On small screens toasts always span the chosen edge. Top toasts slide in from the top, stack downwards and swipe up to dismiss.

These buttons each use their own provider so you can compare them. Your app mounts one.

function Show({ position }) {
  const toast = useToastManager()
  return (
    <Button onClick={() => toast.add({ title: 'Link copied', description: position })}>
      {position}
    </Button>
  )
}
function Positions() {
  return (
    <div className='flex flex-wrap gap-2'>
      {['bottom-end', 'bottom-center', 'top-end', 'top-center'].map((position) => (
        <Toast.Provider key={position}>
          <Show position={position} />
          <Toast.Viewport position={position} />
        </Toast.Provider>
      ))}
    </div>
  )
}
render(<Positions />)

Clearing sticky UI

A fixed bar, cookie banner or chat button can cover the toasts. Set --toast-viewport-offset-bottom to its height, on Toast.Viewport or any ancestor, and the stack moves up by that much. Top positions read --toast-viewport-offset-top. Reach for the offset before moving toasts to the top.

In a Navigator app, top toasts already clear the tallest Pane.Header along the top of the window and follow it as it collapses. Set --toast-viewport-offset-top only for other fixed UI; it adds to that.

function Checkout() {
  const [barShown, setBarShown] = useState(false)
  return (
    <Toast.Provider>
      <div className='flex flex-wrap gap-2'>
        <Button onClick={() => setBarShown(!barShown)}>
          {barShown ? 'Hide' : 'Show'} checkout bar
        </Button>
        <SaveForLater />
      </div>
      {barShown &&
        createPortal(
          <div
            data-checkout-bar
            className='fixed inset-x-0 bottom-0 z-50 flex h-20 items-center justify-end px-6 emphasis-raised'
          >
            <Button>Continue</Button>
          </div>,
          document.body
        )}
      <Toast.Viewport
        style={{ '--toast-viewport-offset-bottom': barShown ? '5rem' : '0px' }}
      />
    </Toast.Provider>
  )
}
function SaveForLater() {
  const toast = useToastManager()
  return (
    <Button onClick={() => toast.add({ title: 'Saved for later', intent: 'success' })}>
      Save for later
    </Button>
  )
}
render(<Checkout />)

In your own CSS you can set it wherever the bar appears:

:root:has([data-checkout-bar]) {
  --toast-viewport-offset-bottom: 5rem;
}

Timing

A toast stays for the provider's timeout, 5000ms by default, or its own timeout if you pass one. The bar along its bottom empties in that time. Hovering or focusing the toasts pauses every timer and the bar with it, and they carry on from the same point afterwards. They also pause while the window is in the background. F6 moves focus to the toasts from anywhere on the page.

timeout: 0 keeps a toast until it's dismissed and drops the bar. So does a promise toast while it's loading. It starts its timer when the work settles.

With an action

actionProps adds a small button. It takes any button props, with the label as children. Keep it to one short verb, such as Undo. A toast with a convenience action like Undo still times out, but give it longer to read and reach, about 8000ms.

function SaveEvent() {
  const toast = useToastManager()
  function save() {
    toast.add({
      title: 'Event saved',
      description: 'Midnight Static at The Lantern Room, Fitzroy',
      intent: 'success',
      timeout: 8000,
      actionProps: {
        children: 'Undo',
        onClick: () => toast.add({ title: 'Changes undone' })
      }
    })
  }
  return <Button onClick={save}>Save event</Button>
}
render(<SaveEvent />)

When the action is the only way forward, such as Retry, set timeout: 0 so the toast waits for them. If the problem needs more than a retry, show a Callout next to it instead.

function SaveTicketTypes() {
  const toast = useToastManager()
  function fail() {
    toast.add({
      title: 'Ticket types not saved',
      description: 'We lost the connection. Your changes are still here.',
      intent: 'danger',
      timeout: 0,
      actionProps: {
        children: 'Retry',
        onClick: () => toast.add({ title: 'Ticket types saved', intent: 'success' })
      }
    })
  }
  return <Button onClick={fail}>Save ticket types</Button>
}
render(<SaveTicketTypes />)

Promise

promise shows a spinner while the work runs, then swaps in the success or error toast. It returns the promise, so you can still await the result.

function PublishEvent() {
  const toast = useToastManager()
  function publish(succeeds) {
    const request = new Promise((resolve, reject) =>
      setTimeout(
        () => (succeeds ? resolve('Harbourlight Sessions') : reject()),
        2000
      )
    )
    toast.promise(request, {
      loading: 'Publishing Harbourlight Sessions',
      success: (name) => ({
        title: `${name} is live`,
        description: 'Tickets go on sale Friday at 9am.'
      }),
      error: {
        title: 'Harbourlight Sessions not published',
        description: 'We lost the connection. Try again in a moment.'
      }
    })
  }
  return (
    <div className='flex flex-wrap gap-2'>
      <Button onClick={() => publish(true)}>Publish event</Button>
      <Button onClick={() => publish(false)}>Publish, then fail</Button>
    </div>
  )
}
render(<PublishEvent />)

If the work fails because something needs fixing, such as missing event details, show a Callout next to the problem instead. It stays until the problem is fixed.

Updating a toast

add returns an id. Pass it to update to change the toast in place, or to close to dismiss it.

function Upload() {
  const toast = useToastManager()
  function upload() {
    const id = toast.add({ title: 'Uploading poster', timeout: 0 })
    setTimeout(
      () =>
        toast.update(id, {
          title: 'Poster uploaded',
          intent: 'success',
          timeout: 5000
        }),
      1500
    )
  }
  return <Button onClick={upload}>Upload poster</Button>
}
render(<Upload />)

Outside React

createToastManager makes a manager you can call from anywhere, such as a fetch wrapper or a store. Pass it to Toast.Provider. It has the same add, update, close and promise as the hook.

// toasts.ts
import { createToastManager } from '@oztix/roadie-components/toast'

export const toasts = createToastManager()

// providers.tsx
<Toast.Provider toastManager={toasts}>
  {children}
  <Toast.Viewport />
</Toast.Provider>

// api.ts
toasts.add({ title: 'Session expired', intent: 'warning' })

Composition

Toast.Viewport renders every toast for you. To lay a toast out differently, pass your own list as children and build each one from its parts. Toast.Title, Toast.Description and Toast.Action fill themselves from the toast, Toast.Icon picks the intent's icon, and Toast.Progress draws the time-left bar.

function Toasts() {
  const { toasts } = useToastManager()
  return toasts.map((toast) => (
    <Toast key={toast.id} toast={toast}>
      <Toast.Content>
        <Toast.Icon />
        <div className='grid min-w-0 flex-1 gap-0.5'>
          <Toast.Title />
          <Toast.Description />
        </div>
        <Toast.Action />
        <Toast.Close />
        <Toast.Progress />
      </Toast.Content>
    </Toast>
  ))
}

<Toast.Viewport>
  <Toasts />
</Toast.Viewport>

Guidelines

timeout: 8000,
actionProps: { children: 'Undo', onClick: undo }

Accessibility

• Toasts are announced politely by a live region. Pass priority: 'high' for an urgent message so it is announced straight away.
• F6 moves focus to the toast region. Tab moves through the toasts' actions and dismiss buttons, and Escape dismisses the focused toast.
• Hovering or focusing the region fans the stack out and pauses every timer.
• The time-left bar is hidden from screen readers. With reduced motion it isn't shown, since it can't empty smoothly.
• Swipe towards the viewport's edge, or sideways, to dismiss on touch.
• With reduced motion, toasts appear and leave without sliding.
• The dismiss button is labelled Dismiss. Pass aria-label to Toast.Close to change it.

Hooks

useToastManager

function useToastManager(): UseToastManagerReturnValue

Reads the nearest Toast.Provider. createToastManager() returns the same methods, without toasts.

add takes title, description, intent, actionProps, timeout, priority, onClose and data. Pass an existing id to replace that toast.