HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
ToastView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorThe region that holds toast messages, and the only element that announces them.StableSince 0.1.0OverlaysUsageimport'@fusion.dev/helix/toast'import'@fusion.dev/helix-headless/toast'Preview
API ReferenceRoothelix-toastThe region that holds toast messages, and the only element that announces them.
PropTypeDescriptionhotkeystringDefault"F8"The key that takes focus to the stack and back, such as F8 or Alt+T:
keys joined by +, the last one the key, as Announcement's hotkey
reads them: mod is Command on Apple devices and Control elsewhere.
Empty turns it off.labelstringDefault"Notifications ({hotkey})"Accessible name for the region, with {hotkey} filled in. Translate it with
the rest of your interface.maxVisiblenumberHow many messages show at once. The messages after that many wait, hidden
and with their timers stopped, until a message before them goes. Unset,
every message shows.placement"bottom-center"|"bottom-end"|"bottom-start"|"top-center"|"top-end"|"top-start"Which corner or edge the stack sits at.swipeDirection"bottom"|"end"|"start"|"top"The edge a touch or a pen swipes a message toward to dismiss it: end,
the end of the line, or start, top or bottom. Unset is end.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The messages.
EventTypeDescriptionhelix-dismissHelixDismissEventA message is being dismissed, by its control or by its timer. The message sends it, and you can listen for it on the region. Cancelable: canceling it keeps the message.
MethodTypeDescriptionadd(message: string, options: {
action?: Elementdismissible?: booleanduration?: numberheading?: stringtone?: "danger" | "info" | "success" | "warning"
}) => HTMLElementShows a message from script, and returns the element.
PartDescriptionliveThe two regions that say each message as it arrives, a polite status and an assertive alert, inside the stack. Empty at rest, and hide them with the standard clip, never display: none.regionThe stack the messages are in. It is in the top layer while a message shows, and takes focus from hotkey where no message holds a control.
CSS PropertyDescription--toast-gapSpace between one message and the next.--toast-inline-sizeWidth of a message.--toast-insetDistance from the edges of the window.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Itemhelix-toast-itemOne message in the toast region.
PropTypeDescriptiondismissiblebooleanDefaultfalseWhether the element shows a control that dismisses it.dismissLabelstringDefault"Dismiss"The dismiss control's label, read by screen readers.durationnumberHow long the message stays, in milliseconds. When it is not set, the
message stays until it is dismissed. The attribute also takes a CSS time,
such as 5s.openbooleanWhether the message is still showing.tone"danger"|"info"|"success"|"warning"The kind of message, which sets its mark and the mark's accessible name.waitingbooleanDefaultfalseWhether the region holds the message back, because more messages are
showing than its max-visible. The region sets it. A waiting message is
hidden, its timer has not started, and it is said once it shows.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The message.actionsActions for the message, usually a button or a link.descriptionA line of detail under the heading, which describes the message.dismiss-iconReplaces the glyph inside the dismiss control.headingThe message's title, which names it.iconReplaces the tone mark. The name matches Callout. The dismiss control's glyph uses dismiss-icon, because two slots cannot share a name: content goes to whichever slot comes first in the tree, and the tone mark is the one you are more likely to replace.
EventTypeDescriptionhelix-dismissHelixDismissEventFired when the message is dismissed, by the control or by its timer, and cancelable. Canceling it keeps the message.
MethodTypeDescriptiondismiss() => booleanFires helix-dismiss, and returns false if a listener cancels it.pause() => voidPauses the dismiss timer and keeps the time that is left.resume() => voidRestarts the dismiss timer from where it paused.
PartDescriptionactionsThe region that holds the actions.contentThe message.descriptionThe slot the description is in. It draws no box until you give it one.dismissThe control that dismisses the message.dismiss-markThe glyph on the dismiss control, where none is slotted.headingThe slot the heading is in. It draws no box until you give it one.iconThe tone mark, where the message has one.icon-markThe tone glyph, where none is slotted.itemThe message's own surface.timerThe bar showing how long is left, where a duration was given.
CSS PropertyDescription--toast-background-colorThe panel's color. Follows --helix-color-surface-overlay.--toast-border-colorColor of the panel's edge.--toast-border-widthWidth of the panel's edge. Follows --helix-border-floating, which is 0, so the panel stands out by its shadow unless your theme sets a border.--toast-colorColor of the message's text.--toast-description-colorColor of the line in the description slot, under the heading.--toast-dismiss-colorColor of the dismiss control's mark at rest.--toast-durationHow long this message stays, in milliseconds, for a progress hint.--toast-font-sizeSize of the message's text. The first line's controls and mark stay centered on it.--toast-heading-weightWeight of the heading in the heading slot.--toast-item-paddingSpace between the message's edge and its contents.--toast-radiusRounding of the panel's corners.--toast-shadowShadow under the panel. Follows --helix-shadow-floating. A floating surface can sit over any content, so it has a shadow by default.--toast-swipe-xHow far a swipe has moved the message across, in pixels, toward the right.--toast-swipe-yHow far a swipe has moved the message down, in pixels, under a swipe-direction of top or bottom.--toast-timer-sizeThickness of the bar that counts down a timed message.--toast-tone-colorColor of the mark and the countdown bar. Unset, each tone takes its own color, so set it per tone, as in helix-toast-item[tone="danger"].
Custom stateDescriptionclosedThe message has been dismissed and is hidden, or leaving.pausedThe dismiss timer is paused, while a pointer or focus is on the message or in the stack, or while the page is hidden.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.waitingThe region holds the message back, past its max-visible, until a message before it goes.
Roothelix-headless-toastThe region that holds toast messages, and the only element that announces them.
PropTypeDescriptionhotkeystringDefault"F8"The key that takes focus to the stack and back, such as F8 or Alt+T:
keys joined by +, the last one the key, as Announcement's hotkey
reads them: mod is Command on Apple devices and Control elsewhere.
Empty turns it off.labelstringDefault"Notifications ({hotkey})"Accessible name for the region, with {hotkey} filled in. Translate it with
the rest of your interface.maxVisiblenumberHow many messages show at once. The messages after that many wait, hidden
and with their timers stopped, until a message before them goes. Unset,
every message shows.placement"bottom-center"|"bottom-end"|"bottom-start"|"top-center"|"top-end"|"top-start"Which corner or edge the stack sits at.swipeDirection"bottom"|"end"|"start"|"top"The edge a touch or a pen swipes a message toward to dismiss it: end,
the end of the line, or start, top or bottom. Unset is end.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The messages.
EventTypeDescriptionhelix-dismissHelixDismissEventA message is being dismissed, by its control or by its timer. The message sends it, and you can listen for it on the region. Cancelable: canceling it keeps the message.
MethodTypeDescriptionadd(message: string, options: {
action?: Elementdismissible?: booleanduration?: numberheading?: stringtone?: "danger" | "info" | "success" | "warning"
}) => HTMLElementShows a message from script, and returns the element.
PartDescriptionliveThe two regions that say each message as it arrives, a polite status and an assertive alert, inside the stack. Empty at rest, and hide them with the standard clip, never display: none.regionThe stack the messages are in. It is in the top layer while a message shows, and takes focus from hotkey where no message holds a control.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Itemhelix-headless-toast-itemOne message in the toast region.
PropTypeDescriptiondismissiblebooleanDefaultfalseWhether the element shows a control that dismisses it.dismissLabelstringDefault"Dismiss"The dismiss control's label, read by screen readers.durationnumberHow long the message stays, in milliseconds. When it is not set, the
message stays until it is dismissed. The attribute also takes a CSS time,
such as 5s.openbooleanWhether the message is still showing.tone"danger"|"info"|"success"|"warning"The kind of message, which sets its mark and the mark's accessible name.waitingbooleanDefaultfalseWhether the region holds the message back, because more messages are
showing than its max-visible. The region sets it. A waiting message is
hidden, its timer has not started, and it is said once it shows.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The message.actionsActions for the message, usually a button or a link.descriptionA line of detail under the heading, which describes the message.dismiss-iconReplaces the glyph inside the dismiss control.headingThe message's title, which names it.iconReplaces the tone mark. The name matches Callout. The dismiss control's glyph uses dismiss-icon, because two slots cannot share a name: content goes to whichever slot comes first in the tree, and the tone mark is the one you are more likely to replace.
EventTypeDescriptionhelix-dismissHelixDismissEventFired when the message is dismissed, by the control or by its timer, and cancelable. Canceling it keeps the message.
MethodTypeDescriptiondismiss() => booleanDismisses the message, and returns whether the dismissal went ahead.pause() => voidPauses the dismiss timer and keeps the time that is left.resume() => voidRestarts the dismiss timer from where it paused.
PartDescriptionactionsThe region that holds the actions.contentThe message.descriptionThe slot the description is in. It draws no box until you give it one.dismissThe control that dismisses the message.dismiss-markThe glyph on the dismiss control, where none is slotted.headingThe slot the heading is in. It draws no box until you give it one.iconThe tone mark, where the message has one.icon-markThe tone glyph, where none is slotted.itemThe message's own surface.timerThe bar showing how long is left, where a duration was given.
CSS PropertyDescription--toast-durationHow long this message stays, in milliseconds, for a progress hint.--toast-swipe-xHow far a swipe has moved the message across, in pixels, toward the right.--toast-swipe-yHow far a swipe has moved the message down, in pixels, under a swipe-direction of top or bottom.
Custom stateDescriptionclosedThe message has been dismissed and is hidden, or leaving.pausedThe dismiss timer is paused, while a pointer or focus is on the message or in the stack, or while the page is hidden.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.waitingThe region holds the message back, past its max-visible, until a message before it goes.
Examples
NameDescriptionArrivingSeveral toasts stacking as they arrive.Auto DismissA toast that closes on its own after eight seconds.Color ModeToasts that stay in light mode, set with data-color-mode, whatever mode the page is in.EventsA message sends helix-dismiss, and your code decides whether it closes.PreviewA message over the page, in the corner set by its placement.PreviewA message over the page, in the corner set by its placement.QueueTwo toasts at a time, with the next shown when you dismiss one.TonesToasts with no tone and in the info, success, warning, and danger tones.