Toast

​

What it is

A toast is a notification that appears at the corner of the screen in response to something the reader just did, then disappears on its own after a few seconds. It is not part of the page layout — it floats above everything else, is queued rather than placed, and does not require the reader to do anything to make it go away. That self-dismissal is what separates it from an alert, which stays in place until the reader fixes the condition, dismisses it, or the state changes. A success message with nothing further to say is a toast; a message the reader needs to keep referring back to is an alert. Toast is not a single component you place on a page. It is a queue: TitanToastProvider wraps the application once, and showToast(message, options) pushes a notification into it from anywhere — a click handler, a mutation callback, an error boundary — with no JSX to render at the call site.

​

Live example

​

Exports

Verified directly from Toast/index.js, ToastComponent.tsx, and TitanToastProvider.tsx — no per-component prop emitter exists yet for this concept, so this table is hand-confirmed rather than generated. options accepts variant ("success" | "error" | "warning" | "info"), persist (boolean), and the underlying library’s own queueing options (autoHideDuration, anchorOrigin, and so on) — confirmed from ToastComponent’s destructured props and TitanToastProvider’s defaults.

​

Vocabulary

Variant is the same four-way severity split as Alert — success, error, warning, info — and it draws from the identical -alt token family (background-{severity}-alt, icon-{severity}-alt). The two components share a visual vocabulary for severity even though nothing in source names that sharing explicitly.

​

Choose Toast when

• The message confirms something that just happened, and there is nothing more for the reader to do about it.
• It is fine for the reader to miss it — the underlying state change already took effect, and the toast is a courtesy, not the only record of what happened.
• The trigger is an action, not something present when the page loads.

​

Choose something else when

​

Anatomy

There is no title, no trailing action, and no severity-neutral form — unlike Alert, a toast is always exactly one of the four variants and always carries the matching icon.

​

Variants, sizes, and states

Two dismissal modes, controlled by persist: Stacking defaults to top-right, dense spacing, and up to 3 at once — all confirmed from TitanToastProvider’s configuration, and all are the underlying queue’s own options rather than a Titan-specific model. A 4th toast beyond maxSnack queues rather than rendering immediately; if all 3 currently showing are persist: true (so none is due to auto-dismiss and free a slot), the oldest is force-dismissed to make room — confirmed from the queue library’s own internal messaging for that condition, not from a Titan-authored rule.

​

Edge and failure states

​

Tokens

Verified directly from ToastComponent.tsx — no per-component token emitter exists yet for this concept, so this table is hand-confirmed rather than generated. This is the same -alt family Alert uses for its four severities — see Alert’s tokens.

​

Composition

TitanToastProvider wraps the application once, typically at or near the root — not per page or per feature. Every showToast call anywhere in the tree reaches the same queue and renders into the same portal at the document body. Toasts are called, not rendered. There is no JSX for an individual toast in normal use; a component that wants one calls showToast from an event handler, a mutation’s onCompleted, or similar, and never holds toast state itself.

​

Content

• State what happened, in the past tense, in one short line — the fixed width and short auto-dismiss window both push against long copy.
• No severity words in the message. The icon and color already carry error/warning, the same rule as Alert.
• Do not put the only record of an important outcome in a toast. If the reader needs to find this information again later, it also needs a permanent home — a toast that dismisses itself does not persist anywhere once it’s gone.

​

Accessibility

Every toast renders with role="alert", unconditionally — confirmed directly in ToastComponent.tsx, on the wrapping element, regardless of variant. Unlike an Alert, where role="alert" is only correct for content that appears after page load, a toast is always triggered by something happening after load — it is never present at first render — so the same role is correct here without the caveat Alert needs. The variant icon’s accessible treatment is unconfirmed. Nothing in ToastComponent.tsx marks the icon aria-hidden, and no test exercises how a screen reader announces it alongside the message text. A toast that auto-dismisses in 5 seconds may not give a screen reader user enough time to finish hearing it, particularly a longer message. This is not handled specially — the same default duration applies regardless of message length or announcement speed. Passing persist: true for a longer or more consequential message is the only available mitigation today.

​

Constraints

​

Known issues

​

Why it works this way

Toast is a queue, not a component you place, because its whole value is not competing for layout. A notification that had to be slotted into a page’s regions would need the page to have reserved space for it, and most of the time nothing is queued. Making it a call — showToast — rather than a rendered element is what lets any part of the app trigger one without owning where it appears. The fixed width is the tradeoff for that same portability. A toast rendered from anywhere cannot size itself to a parent container it isn’t inside, so it takes one width regardless of content, and long messages wrap rather than the box growing.

​

Status

​

Related

The generated adoption report for this component shows zero usages, matched against a literal <Toast /> JSX tag. That is very likely a tooling artifact rather than true non-adoption: real call sites invoke showToast(...) as a function and never render a <Toast> element, so a tag-based scan would undercount it the same way — confirmed here as a limitation of the generated figure, not evidence nobody uses toasts. Treat the adoption count for this component as unreliable until the scanning approach accounts for function-call usage.

• Alert — the persistent counterpart; read its “Choose something else when” table for the other half of this distinction
• Banner — the product-wide, durable notice Toast is not, and which Titan does not currently ship
• Error handling — where toasts fit alongside alerts and inline errors