Build a toast system and a notifications inbox that share one queue

Overview

Two surfaces, one data source. Toasts are transient — they slide in, sit for a few seconds, slide out. The inbox is a persistent timeline of everything the user might want to revisit.

Most apps confuse the two: a "Saved!" confirmation gets added to a notifications inbox the user has to clean up, or a failed background job pops a toast that disappears before the user reads it. The split here is hard: toasts are for right now; the inbox is for later. The system decides which channel each event goes to.

Errors get toasts. Successes might not. A successful save the user just triggered doesn't need its own slide-in — the row updated, that's the confirmation. Reserve toasts for things the user couldn't see otherwise: failures, background completions, async results.

Toasts use the design-system tone-danger token for failures. Never red — red is a theme decision; tone-danger is a semantic one, and a brand re-skin updates both toasts and inline errors in lockstep.

Skip this recipe if your app has no async work and no background events. A purely synchronous form doesn't need toasts; the inline error message under each field is enough.

What you'll build

A toast on desktop, the same event in the inbox bell, and the mobile-stacked variant.

Required pieces

Everything this recipe pulls from @corelithzw/react.

@corelithzw/react exports used here: Toast, ToastProvider, useToast, Stack, Button. The provider owns the queue; useToast dispatches into it.

Step-by-step build

Every toast has a persistent flag — does this event also belong in the inbox? Successes that are reversible (undo) belong in the inbox; an autosave confirmation doesn't. The provider routes accordingly.

The queue is a single array in a provider context. Components dispatch via useToast; the provider owns dismissal, auto-expiry timers, and writes persistent toasts into the inbox. Two surfaces, one queue.

The toast region is fixed-position and renders the visible queue. On desktop it lives at top-right; on mobile it slides from the top, centred. Stacking is capped at three visible — older ones queue up behind, not above.

The bell shows the count of unread inbox items; clicking opens a popover with the full timeline. Clicking an entry marks it read. The inbox is purely visual on the client — no special API; it's just the persistent slice of the queue.

Final composition

The whole NotificationsCenter, assembled. Provider + region + bell + a sample async handler that uses both surfaces.

Variations

Three common forks. Each is a small diff from the final composition.

// Add a `silent` flag to ToastRecord
case 'PUSH': {
  const inbox = a.toast.persistent
    ? [a.toast, ...s.inbox].slice(0, 200) : s.inbox;
  const queue = a.toast.silent
    ? s.queue : [...s.queue, a.toast];
  return { queue, inbox };
}

useEffect(() => {
  const ws = new WebSocket(WS_URL);
  ws.onmessage = (m) => {
    const e = JSON.parse(m.data);
    push({
      tone: e.severity, title: e.title,
      description: e.body, persistent: true,
    });
  };
}, [push]);

// Each toast can carry a `groupKey`
const last = s.queue[s.queue.length - 1];
if (last?.groupKey === a.toast.groupKey) {
  last.count = (last.count ?? 1) + 1;
  return { ...s };
}

Accessibility

What this recipe takes care of for you.

• Toasts announce themselves. Danger toasts use aria-live="assertive" (interrupt), everything else uses polite. Errors should not be missed.
• The region is named. role="region" + aria-label="Notifications" on the toast container so screen-reader users can jump to it via landmark navigation.
• Action buttons are real buttons. "Undo" / "Retry" are <Button> elements inside the toast, not clickable text. Tab from the toast lands on the action.
• Dismiss has a label. The X button on each toast carries aria-label="Dismiss". Mouse and keyboard users have parity.
• The bell announces unread count. aria-label="Notifications, 3 unread" updates as the inbox changes — screen readers re-announce on focus.
• Auto-dismiss respects motion preferences. Slide animation is replaced with an instant fade when prefers-reduced-motion: reduce is set.
• Touch dismiss works. Swipe-right on mobile dismisses a toast; the same gesture is bound to the Esc key handler so keyboard users get the same outcome.

Related recipes

Other state-and-feedback recipes.