ToastRegion
The live region is always in the page (a region added together with its text is often not announced); only the toast inside it comes and goes, dismissing itself after DISMISS_MS.
import { ToastRegion } from '@ergasti/bricks';Examples
Toast
One message at a time, announced politely, dismissed after five seconds or with its close button. Say the outcome ("Approved. Sara gets a WhatsApp."), and offer one action such as Undo. The toast is fixed to the corner of the screen, so this example sits in a contained frame.
Code
import { useState } from 'react';
import { Button, ToastRegion, type ToastMessage } from '@ergasti/bricks';
function Outcome() {
const [toast, setToast] = useState<ToastMessage | null>(null);
return (
<div>
<Button onClick={() => setToast({ message: 'Approved. Sara gets a WhatsApp.', actionLabel: 'Undo', onAction: () => setToast(null) })}>Approve</Button>
<ToastRegion toast={toast} onDismiss={() => setToast(null)} />
</div>
);
}Props
Prop
Type
Labels
Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key toast, or with the component's own prop where it has one. A {name} is a value the component fills in.
| Key | English | Arabic |
|---|---|---|
close | Close | اقفل |
Design guidance
How the BRICKS design system uses ToastRegion. Written in docs/content/components/ToastRegion.md; the props above are read from the code, which wins where the two disagree.
A polite live region that shows one short outcome toast at a time, with an optional action such as Undo; mount it once per page and feed it the latest message.
The region (role="status") is always in the page; only the toast inside it appears and disappears, because a region added together with its text is often not announced. Each toast dismisses itself after 5 seconds. It is the mock's .toast: the dark pill at the bottom centre of both dashboards that confirms "Invite link copied", "CSV of this list downloaded" or "Coupon KARI0329 paused. Undo".
Anatomy
- Region:
.kit-toast-region, an emptydiv role="status" aria-live="polite"that stays mounted. - Toast pill:
.kit-toast, fixed 24px above the bottom edge, centred, ink background, white 600 text, radius 99, up to 560px wide. - Message: the outcome sentence (
toast.message). - Action (optional):
.kit-toast-act, an outline pill button in lime text, shown when bothactionLabelandonActionare set. - Close:
.kit-toast-x, a 28px round button with an X icon, named by the copy'sclose("Close" / "اقفل").
Variants
| Value | Look | When to use |
|---|---|---|
Message only ({ message }) | Pill with text and close | A finished action that needs no follow-up: "Invite link copied". |
With action ({ message, actionLabel, onAction }) | Adds a lime outline button before close | A reversible action: "Coupon KARI0329 paused." + Undo. |
States
| State | Trigger |
|---|---|
| Empty | toast={null}: the region renders with no children. |
| Shown | toast set: the pill slides in (200 ms kit-slide-in; no animation under prefers-reduced-motion). |
| Auto-dismiss | 5000 ms after each new toast object, onDismiss is called. The timer restarts only when toast changes. |
| Dismissed by user | Close calls onDismiss. |
| Focus-visible | Buttons inside the dark pill use the inverse focus ring (--focus-ring-inverse). |
| Mobile (< 860px) | Sits above the bottom nav (--bottom-nav-height + 20px + safe area); action and close grow to 44px. |
Types
| Field | Type | Required | Description |
|---|---|---|---|
message | string | yes | A concrete outcome sentence: "Approved. Sara gets a WhatsApp." |
actionLabel | string | no | The action button's text ("Undo"). Needs onAction. |
onAction | () => void | no | Runs the action. The toast stays until dismissed or timed out. |
Usage
const [toast, setToast] = useState<ToastMessage | null>(null);
<>
<CopyLinkField value="trndr.app/join/glowco" onCopied={() => setToast({ message: 'Invite link copied' })} />
<ToastRegion toast={toast} onDismiss={() => setToast(null)} />
</>// Reversible action with Undo
setToast({
message: 'Coupon KARI0329 paused.',
actionLabel: 'Undo',
onAction: () => { resumeCoupon('KARI0329'); setToast(null); },
});// PR Portal approvals: one region for the page, under the shell
<AppShell {...shell}>
<PrApprovals onApprove={(r) => setToast({ message: `Approved. ${r.name} gets a WhatsApp.` })} />
<ToastRegion toast={toast} onDismiss={() => setToast(null)} language="en" />
</AppShell>Where it appears
- In the v3 mocks: Brand › every screen › the toast (
.toast): "Invite link copied", "CSV of this list downloaded", "Opens card top-up (Paymob)", plus the mock's built strings "Added to <group name>" and "Gift list saved · <n> products". PR Portal › every screen › the toast with an Undo button. - Screens: shown on BrandHome and PrApprovals when an action fires.
Guidelines
Do
- Mount one
ToastRegionper page, high in the tree, and keep it mounted. - Write the outcome, not the action: "Saved. Your creators see the new rate on their next order."
- Offer Undo only when the action can really be reversed.
Don't
- Don't put errors that need a decision in a toast; use a
Banner tone="bad"or the form's error. - Don't stack toasts: a new one replaces the old.
- Don't mount the region conditionally together with its message; screen readers may skip it.
RTL and Arabic
- Centred with
inset-inline-start: 50%; in RTL the translate flips (50%) so it stays centred. - The close label switches to Arabic with
language="ar". Write the message in the viewer's language; numbers and codes (KARI0329) keep Latin digits.
Tokens
--ink (background), --lime (action text), --focus-ring-inverse, --bottom-nav-height, --min-touch-target.
Accessibility
role="status"witharia-live="polite": the message is announced without moving focus.- The close button has an accessible name from copy ("Close" / "اقفل"); the X icon is
aria-hidden. - Buttons are real
<button type="button">. On touch tiers (≤1024px) a transparent::beforeextends their hit area to 44px (--min-touch-target); under 860px they are 44px themselves. On desktop they are 28px. - Inverse focus ring on the dark pill. Motion is removed under
prefers-reduced-motion. - 5 s is short: never put the only path to an action inside a toast.
Found in the source
- Roles in the markup:
status. - ARIA attributes set:
aria-live,aria-label,aria-hidden.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
Banner: persistent page-level status or alert.CopyLinkField/CouponChip: show their own "Copied" state inline; pair with a toast only if the copy happens out of view.SaveBar: unsaved-change bar, not a confirmation.
See also: Button · AsyncBlock · Skeleton
Source
src/kit/Toast.tsx (line 20) on GitHub.