Toast

Brief, non-blocking notifications stacked in the corner of the screen.

import { Button, ToastProvider, useToast } from "@merid/react";

function SaveButton() {
  const { toast } = useToast();
  return (
    <Button
      onClick={() =>
        toast({ title: "Changes saved", description: "Your workspace settings are up to date.", tone: "success" })
      }
    >
      Save changes
    </Button>
  );
}

export function App() {
  return (
    <ToastProvider>
      <SaveButton />
    </ToastProvider>
  );
}

Import

tsx

import { ToastProvider, useToast } from "@merid/react";

Anatomy

Toasts are imperative. Wrap the app once in ToastProvider, then call toast() from useToast anywhere below it.

tsx

<ToastProvider>
  <App /> {/* const { toast, dismiss } = useToast(); */}
</ToastProvider>

Each toast renders a status dot, a title, an optional description, an optional action button and a dismiss button. The provider portals a labelled region with a polite live list to the bottom-right of the viewport.

Examples

Tones

The tone only changes the status dot colour.

toast({ title: "A neutral toast", tone: "neutral" });
toast({ title: "A info toast", tone: "info" });
toast({ title: "A success toast", tone: "success" });
toast({ title: "A warning toast", tone: "warning" });
toast({ title: "A danger toast", tone: "danger" });

Action, persistence and dismiss

duration: Infinity keeps a toast until it is dismissed. Choosing the action runs onClick and dismisses the toast. Reusing an id replaces the existing toast instead of stacking a new one.

const { toast, dismiss } = useToast();

toast({
  id: "archive", // reusing an id replaces the existing toast
  title: "Project archived",
  duration: Infinity, // stays until dismissed
  action: { label: "Undo", onClick: () => toast({ title: "Project restored", tone: "success" }) },
});

dismiss(); // removes every toast

API reference

ToastProvider

Prop	Type	Default	Description
`children`	`ReactNode`	–	App content.
`duration`	`number`	`5000`	Default auto-dismiss delay in ms.
`limit`	`number`	`3`	Maximum toasts visible at once; oldest are dropped.
`label`	`string`	`"Notifications"`	Accessible name of the notification region.

useToast()

Returns ToastApi. Throws when called outside ToastProvider.

Prop	Type	Default	Description
`toast`	`(options: ToastOptions) => string`	–	Shows a toast and returns its id.
`dismiss`	`(id?: string) => void`	–	Removes a toast by id, or all toasts when omitted.

ToastOptions

Prop	Type	Default	Description
`title`Required	`ReactNode`	–	Short headline.
`description`	`ReactNode`	–	Optional supporting text.
`tone`	`"neutral" \| "info" \| "success" \| "warning" \| "danger"`	`"neutral"`	Status dot colour.
`duration`	`number`	`provider duration`	Auto-dismiss after this many ms; Infinity keeps it until closed.
`action`	`{ label: string; onClick: () => void }`	–	Optional action button.
`id`	`string`	–	Reuse an id to replace an existing toast; its timer restarts with the new `duration`.

Styling

Class	Element
`.mrd-toast-region`, `.mrd-toast-region__list`	Region and live list
`.mrd-toast`	One toast
`.mrd-toast__dot`	Status dot
`.mrd-toast__body`, `.mrd-toast__title`, `.mrd-toast__description`	Text
`.mrd-toast__action`	Action button
`.mrd-toast__close`	Dismiss button

Attribute	On	Values
`data-tone`	`.mrd-toast`	`neutral`, `info`, `success`, `warning`, `danger`

Accessibility

Toasts follow the WAI-ARIA alert pattern in its polite form: the list is an aria-live="polite" region inside a labelled <section>, so new toasts are announced without interrupting. The auto-dismiss timer pauses while the pointer is over a toast or focus is inside it.

Key	Action
`Tab`	Reach the action and dismiss buttons of visible toasts.
`Enter`	Activate the focused action or dismiss button.
`Space`	Activate the focused action or dismiss button.

Guidelines

Confirm an action the person just took, in a few words: “Changes saved”.

Avoid

Show a toast for something the person can already see change on screen.

Offer Undo on reversible destructive actions and keep that toast until dismissed.

Avoid

Stack several toasts for one event, or use long descriptions.

Alert — persistent inline notice.
AlertDialog — blocking confirmation.