HyToast
Usage examples on this page are written for Lit / plain HTML (
<hy-toast>). The same component ships asHyToastin@whitespaceux/harmony-react(native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.
A toast notification component for displaying transient messages with auto-dismiss.
Toast or alert?
A toast is feedback on an action the user just took — saved, deleted, couldn't save — and leaves on its own. A message that belongs to a place on the page and stays until it no longer applies is hy-alert; a region whose content failed to load is hy-empty-state with a retry.
Key Features:
- Multiple semantic variants (info, success, warning, danger)
- Auto-dismiss with configurable duration
- Pause timer on hover and window focus loss
- Optional dismiss button
- Automatic variant-appropriate icons
- Custom icon support
- Action slot for buttons/links
- Accessible with proper ARIA live region attributes
Accessibility: built in
- Semantic ARIA roles (role="alert" for danger, role="status" for others)
- Visually-hidden variant labels announced by screen readers
- aria-atomic ensures entire toast is announced on updates
- Keyboard accessible dismiss button
- High contrast mode support
- Reduced motion support
Accessibility: your part
- Raise
durationfor a longer message, never lower it below the default, and keeppause-on-hoverandpause-on-focus-losson. - Never move keyboard focus into a toast.
When to use
- Confirming something that just happened and needs no answer: saved, sent, copied, deleted.
- Offering a quick undo for an action that just ran.
Do
- Show one toast at a time for one event.
- Keep it to one short sentence.
When not to use
- Information or an action people must not lose: an
hy-alerton the page, orhy-dialog. A toast can leave unseen, so anything in itsactionslot must also be reachable elsewhere. - A decision needed before going on:
hy-dialog. - A form field's error: the field's own
error-message, beside the field.
Examples
Basic Usage
html
<hy-toast variant="success" open> Your changes have been saved. </hy-toast>With Title
html
<hy-toast variant="info" open label="New Update"> A new version is available. </hy-toast>Custom Duration
html
<hy-toast variant="warning" open duration="10000"> Session expiring in 5 minutes. </hy-toast>Persistent Toast (no auto-dismiss)
html
<hy-toast variant="danger" open duration="0" dismissible>
Connection lost. Please check your network.
</hy-toast>With Action
html
<hy-toast variant="info" open>
File deleted.
<hy-button slot="action" size="small">Undo</hy-button>
</hy-toast>Viewport Positioning (top-right corner)
html
<hy-toast variant="success" open anchor-vertical="top" anchor-horizontal="right">
Settings saved successfully.
</hy-toast>Viewport Positioning (bottom-center)
html
<hy-toast variant="info" open anchor-vertical="bottom" anchor-horizontal="center">
New message received.
</hy-toast>API
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
variant | variant | 'info' | 'success' | 'warning' | 'danger' | 'info' | Visual style variant determining the toast's color scheme and semantic meaning. |
emphasis | emphasis | 'solid' | 'soft' | 'outlined' | 'tinted' | 'tinted' | Visual chrome weight on top of the role. |
dismissible | dismissible | boolean | true | Whether the toast can be dismissed by the user. When true, a close button is displayed. |
open | open | boolean | false | Whether the toast is currently visible. Set to true to show the toast, false to hide it. |
icon | icon | string | undefined | — | Icon name to display. If not provided, a variant-appropriate default icon is used. Set to empty string to hide the icon entirely. |
label | label | string | undefined | — | Title/label for the toast. Displayed as a heading above the message. |
variantLabel | variant-label | string | undefined | — | The visually hidden word read before the message, naming the toast's kind. Unset, it is the English word for the variant with its colon: Information:, Success:, Warning:, Error:. The punctuation is part of the string, so a translation writes its own (Erreur :). Use for internationalization. |
dismissLabel | dismiss-label | string | 'Dismiss toast' | Accessible label for the dismiss button. Use for internationalization. |
duration | duration | number | 5000 | Auto-dismiss duration in milliseconds. Set to 0 or Infinity to disable auto-dismiss. |
pauseOnHover | pause-on-hover | boolean | true | Whether to pause the auto-dismiss timer when hovering over the toast. |
pauseOnFocusLoss | pause-on-focus-loss | boolean | true | Whether to pause the auto-dismiss timer when the window loses focus. |
anchorVertical | anchor-vertical | 'top' | 'bottom' | undefined (no viewport positioning) | Vertical anchor position for viewport positioning. When set, the toast uses fixed positioning relative to the viewport. Combine with anchorHorizontal to position in any of 6 screen locations. |
anchorHorizontal | anchor-horizontal | 'left' | 'center' | 'right' | undefined (no viewport positioning) | Horizontal anchor position for viewport positioning. When set, the toast uses fixed positioning relative to the viewport. Combine with anchorVertical to position in any of 6 screen locations. |
Events
| Event | Detail | Description |
|---|---|---|
show | — | Fired when the toast becomes visible. Detail: { source: HyVisibilitySource } |
hide | — | Fired when the toast is hidden. Detail: { source: HyVisibilitySource } |
request-close | — | Fired before hiding; cancelable to prevent close. Detail: { source: HyVisibilitySource } |
Slots
| Slot | Description |
|---|---|
default | The main toast message content |
action | Optional action buttons or links |
CSS Parts
| Part | Description |
|---|---|
base | The toast's base wrapper element |
icon | The icon container |
content | The content wrapper (title + message) |
title | The title element |
message | The message element |
action | The action slot container |
close-button | The dismiss button (when dismissible) |
CSS Custom Properties
The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.
| Property | Default | Description |
|---|---|---|
--hy-toast-background-info-tinted-rest | var(--hy-background-info-tinted-rest) | One of the generated color hooks (paint/toast.mjs): --hy-toast[-<part>]-<family>-<variant>-<emphasis-or-on>-<state> (family: background, foreground or border), one per cell and state, each falling back to the job token of the same name (the default cell is info tinted). Components ▸ Add an override lists them all. |
--hy-toast-action-background-info-soft-rest | var(--hy-background-info-soft-rest) | One of the slotted action's re-points: --hy-toast-action-background-<role>-<emphasis>-<state> for every tint-reading job of a role-matched hy-button (every soft / tinted state, the outlined / plain hover and press). |
--hy-toast-border-info-rest | var(--hy-border-info-rest) | Info variant border color |
--hy-toast-border-danger-rest | var(--hy-border-danger-rest) | Danger variant border color |
--hy-toast-border-success-rest | var(--hy-border-success-rest) | Success variant border color |
--hy-toast-border-warning-rest | var(--hy-border-warning-rest) | Warning variant border color |
--hy-toast-gap-container-lg | var(--hy-gap-container-lg) | Gap between main toast sections |
--hy-toast-content-gap-container-sm | var(--hy-gap-container-sm) | Gap between content elements (title/message) |
--hy-toast-action-gap-container-sm | var(--hy-gap-container-sm) | Gap between action items |
--hy-toast-padding-container-sm | var(--hy-padding-container-sm) | Padding inside the toast |
--hy-toast-radius-container-md | var(--hy-radius-container-md) | Border radius of the toast |
--hy-toast-stroke-sm | var(--hy-stroke-sm) | Border width |
--hy-toast-overlay-shadow-color | var(--hy-overlay-shadow-color) | Close button hover background |
--hy-toast-shadow-elevation-4 | var(--hy-shadow-elevation-4) | Box shadow for the toast |
--hy-toast-icon-size-lg | var(--hy-icon-size-lg) | Size of the toast icon |
--hy-toast-body-md-font-family | var(--hy-body-md-font-family) | Font family override for toast message |
--hy-toast-min-width | — | Minimum width of the toast |
--hy-toast-surface-width-lg | var(--hy-surface-width-lg) | Maximum width of the toast |
Methods
show()
Shows the toast programmatically.
hide()
Hides the toast programmatically. Emits a cancelable request-close event first.
Parameters:
source- How the close was triggered (for event detail)