Toast — HeroGPUI

Usage

Live example

Rust

1use herogpui::prelude::{Button, Toast, ToastViewport, Variant};
2use gpui::prelude::*;
3use std::time::Duration;
4
5Button::new("toast-usage")
6    .label("Show a toast")
7    .variant(Variant::Secondary)
8    .on_press(|_, _, cx| {
9        Toast::new("Saved")
10            .description("Your changes are live.")
11            .closable(true)
12            .push(Some(std::time::Duration::from_secs(4)), cx);
13    })

Live HeroGPUI compiled to WebAssembly. Select any example without loading another WASM instance.

Anatomy

Rust types

ToastViewportToast

Toast is assembled from these builders. The API reference lists each one.

Customization

Appearance builders and theme tokens Toast uses.

Styling

Toast styling
Style	Description
`absolute ToastViewport`	The root is absolutely placed in the app overlay; z-index, viewport-responsive width, and region focus outline are unavailable.
`ToastPlacement + inset(16)`	Desktop placement and default inset match.
`ToastCardEl`	Card fill, row alignment, six-pixel gap, padding, radius and overlay shadow match; does not add a card border, and cards use flex stacking rather than absolute overlap.
`frontmost + disabled action + hidden close`	Action and close interaction plus close visibility are suppressed; pinned front-height clipping is unavailable.
`text_col flex_col flex_1`	The growing column and adjacent title/description rows match; uses flex stacking rather than the absolute card stack.
`indicator / Spinner`	Geometry, default glyph mapping, spinner size, and overlay/status foreground rules match.
`title_color + 14/20 MEDIUM`	Typography and all five pinned variant title colors match.
`14px/20px muted`	Size and muted foreground match.
`frontmost close_btn`	Size, border, fill, glyph, focus, and frontmost interaction match; keeps it in flow and always visible on the front card.
`Button Secondary Sm`	Desktop action composition matches the small secondary Button; mobile top margin is unavailable.

API reference

Builders

Toast builders
Builder	Type	Default	Description
`placement(ToastPlacement)`	`ToastPlacement`	`ToastPlacement::Bottom`	Positions the application-wide viewport at one of six window anchors.
`gap(Pixels)`	`Pixels`	`12`	Sets the distance between rendered stack entries.
`max_visible_toasts(usize)`	`usize`	`3`	Limits rendered cards without evicting or pausing queued entries.
`scale_factor(f32)`	`f32`	`0.05`	Geometrically narrows cards by stack depth because GPUI div transforms are unavailable.
`width(Pixels)`	`Pixels`	`460`	Sets a fixed desktop card width in pixels.
`toast::toast_store + application-global store`	`ToastQueue<T>`	—	Uses one application-global ToastStore rather than accepting a viewport-local queue.
`push(duration, cx) + ToastData`	`QueuedToast<T>`	`QueuedToast::Required`	ToastData carries the queue id, content, handlers, state, and variant.
`variant(Color)`	`Color`	`Color::Default`	Selects the semantic title and indicator colors.
`title / description / indicator / action / closable`	`AnyElement`	—	The monolithic builder composes indicator, text, action, and close parts from typed data.
`new(title) / description(text)`	`title / text`	—	Title and optional description are composed in the built-in content column.
`indicator(Option<SharedString>)`	`Option<SharedString>`	`Option::VariantIcon`	A caller can replace or suppress the icon by asset path; arbitrary element content is unavailable.
`new(title)`	`title`	—	Required title text is supplied to the constructor.
`description(text)`	`text`	—	Optional description text is composed below the title.
`action(label, handler)`	`label, handler`	—	A text label and press handler create the action button and dismiss its toast.
`closable(bool)`	`bool`	—	The built-in close action can be present or absent but is not otherwise configurable.
`add(store, data, cx) + insert`	`Fn(content, options) -> key`	—	Queues newest-first and returns a stable numeric key.
`close(store, id, cx) + dismiss_toast`	`Fn(key) -> ()`	—	Dismisses one key and reports its onClose exactly once.
`pause_all() + pause_toasts`	`Fn() -> ()`	—	Pauses every active timeout clock while keeping cards interactive.
`resume_all() + pause_toasts`	`Fn() -> ()`	—	Resumes timeout countdown from its remaining duration.
`clear(store, cx) + clear_toasts`	`Fn() -> ()`	—	Drops every entry without emitting per-toast onClose, matching pinned queue lifecycle semantics.
`subscribe(Entity, App, callback)`	`Entity, App, callback`	—	Returns a GPUI Subscription whose drop unsubscribes.
`variant(Color) / success / error`	`Color / ToastVariant`	`Color::Default`	Plain Toast::new now matches the default variant; semantic variants use the builder or constructors.
`is_loading(bool) / loading(title)`	`bool / title`	`false`	Replaces the indicator with a persistent spinner.
`timeout(Duration) / push(duration)`	`Duration / duration`	`4000`	Duration zero persists; positive durations auto-dismiss through the queue timer.
`on_close(callback)`	`Fn() -> ()`	—	Reports exactly once for individual timeout, action, close-button, or programmatic dismissal, but not queue clear.
`loading(title)`	`title`	—	Toast::loading supplies the pending half; orchestration remains caller-owned.

Parts

Toast parts
Part	Description
`ToastViewport`	Application-wide placement, visibility limit, and stacked-card owner.
`Toast`	Queued notification surface and frontmost interaction owner.
`Toast`	Variant glyph, caller asset, or loading spinner.
`Toast`	Built-in title and description column.
`Toast`	Required single-line semantic title.
`Toast`	Optional muted description.
`Toast`	Frontmost small secondary action that dismisses after reporting.
`Toast`	Frontmost keyboard and pointer dismissal action.

States

Toast states
Builder	State	Description
`ToastCardEl.frontmost`	`Frontmost`	Only depth zero exposes action and close interaction; stacked cards are inert.
`toast_card depth + scale_factor`	`Index`	Depth narrows each older card, but uses a flex stack rather than pinned absolute height/translate geometry.
`ToastPlacement`	`Placement`	All six top/bottom start/center/end anchors are driven.
`visible_toasts(max)`	`Hidden`	Overflow remains queued and timed but is not mounted at zero opacity.
`Toast::is_loading`	`Loading`	A persistent spinner replaces the indicator.

Alert Dialog Drawer Modal Popover Tooltip