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.
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 Features:
- 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
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' | 'soft' | 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. |
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 |
title | Optional title displayed above the message (alternative to label prop) |
icon | Custom icon to replace the default variant icon |
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
| Property | Description |
|---|---|
--hy-toast-background-info-tint-subtle | Info variant background |
--hy-toast-background-danger-tint-subtle | Danger variant background |
--hy-toast-background-success-tint-subtle | Success variant background |
--hy-toast-background-warning-tint-subtle | Warning variant background |
--hy-toast-border-info-rest | Info variant border color |
--hy-toast-border-danger-rest | Danger variant border color |
--hy-toast-border-success-rest | Success variant border color |
--hy-toast-border-warning-rest | Warning variant border color |
--hy-toast-foreground-info-rest | Info variant text/icon color |
--hy-toast-foreground-danger-rest | Danger variant text/icon color |
--hy-toast-foreground-default-rest | Message text color |
--hy-toast-foreground-success-rest | Success variant text/icon color |
--hy-toast-foreground-warning-rest | Warning variant text/icon color |
--hy-toast-gap | Gap between main toast sections |
--hy-toast-gap-content | Gap between content elements (title/message) |
--hy-toast-gap-action | Gap between action items |
--hy-toast-action-background-info-tint-light | Slotted action's info hover / pressed tint (the button's background-info-tint-light hook, re-pointed inside the toast) |
--hy-toast-action-background-info-tint-strong | Slotted action's info pressed tint (the button's background-info-tint-strong hook, re-pointed inside the toast) |
--hy-toast-action-background-success-tint-light | Slotted action's success hover / pressed tint (the button's background-success-tint-light hook, re-pointed inside the toast) |
--hy-toast-action-background-success-tint-strong | Slotted action's success pressed tint (the button's background-success-tint-strong hook, re-pointed inside the toast) |
--hy-toast-action-background-warning-tint-light | Slotted action's warning hover / pressed tint (the button's background-warning-tint-light hook, re-pointed inside the toast) |
--hy-toast-action-background-warning-tint-strong | Slotted action's warning pressed tint (the button's background-warning-tint-strong hook, re-pointed inside the toast) |
--hy-toast-action-background-danger-tint-light | Slotted action's danger hover / pressed tint (the button's background-danger-tint-light hook, re-pointed inside the toast) |
--hy-toast-action-background-danger-tint-strong | Slotted action's danger pressed tint (the button's background-danger-tint-strong hook, re-pointed inside the toast) |
--hy-toast-padding | Padding inside the toast |
--hy-toast-radius | Border radius of the toast |
--hy-toast-close-radius | Close button border radius |
--hy-toast-stroke | Border width |
--hy-toast-close-hover-background | Close button hover background |
--hy-toast-shadow | Box shadow for the toast |
--hy-toast-icon-size | Size of the toast icon |
--hy-toast-font-family | Font family override for toast message |
--hy-toast-min-width | Minimum width of the toast |
--hy-toast-max-width | Maximum width of the toast |
--hy-toast-background-info-rest | Info variant solid-emphasis fill |
--hy-toast-background-danger-rest | Danger variant solid-emphasis fill |
--hy-toast-background-success-rest | Success variant solid-emphasis fill |
--hy-toast-background-warning-rest | Warning variant solid-emphasis fill |
--hy-toast-foreground-on-info-rest | Text/icon color on the info solid fill |
--hy-toast-foreground-on-danger-rest | Text/icon color on the danger solid fill |
--hy-toast-foreground-on-success-rest | Text/icon color on the success solid fill |
--hy-toast-foreground-on-warning-rest | Text/icon color on the warning solid fill |
--hy-toast-hover-duration | Close-button hover transition duration |
--hy-toast-hover-easing | Close-button hover transition easing |
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)