HyAlert

Usage examples on this page are written for Lit / plain HTML (<hy-alert>). The same component ships as HyAlert in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

An alert component for displaying important messages to users with semantic variants.

Alert or toast?

An alert stays in the page, next to what it concerns, until it no longer applies. Feedback on an action the user just took — saved, deleted, couldn't save — is hy-toast (an alert also fits a failed action whose form stays on screen); a region whose content failed to load is hy-empty-state with a retry.

Key Features:

• Multiple semantic variants (info, success, warning, danger)
• Optional dismiss button for closeable alerts
• 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 alert is announced on updates
• Keyboard accessible dismiss button
• High contrast mode support
• Reduced motion support

Accessibility: your part

• Show an alert added after an action next to the control that caused it, or move focus to it, so people who use a screen reader or zoom find it.

When to use

• A status about what is on the page that people should see while they work: a warning before they submit, an error in a section, a notice about their account.
• A message that stays until it is dismissed or no longer applies.

Do

• Pick the variant by what the message means: info, success, warning or danger.
• Say what happened and what people can do next.
• Place it next to the content it is about.

When not to use

• The user must decide or confirm before going on: hy-dialog.
• A message about one field: that control's error-message or warning-message.
• Lasting content that reports no status: plain text or a hy-card.
• The status of one item, such as a row or a record: a marker on that item (hy-badge or hy-chip), not an alert.

Examples

Basic Usage

<hy-alert variant="info" open> This is an informational message. </hy-alert>

Dismissible Alert

<hy-alert variant="success" open dismissible> Your changes have been saved successfully. </hy-alert>

With Custom Icon

<hy-alert variant="warning" open icon="warning">
  Please review your input before continuing.
</hy-alert>

With Actions

<hy-alert variant="danger" open>
  Something went wrong. Please try again.
  <hy-button slot="action" size="small">Retry</hy-button>
</hy-alert>

Emphasis variants

<hy-alert variant="success" emphasis="solid" open>High-emphasis success</hy-alert>
<hy-alert variant="success" emphasis="soft" open>Soft success</hy-alert>
<hy-alert variant="success" emphasis="outlined" open>Outlined success</hy-alert>
<hy-alert variant="success" open>Tinted success (the default)</hy-alert>

API

Properties

Property	Attribute	Type	Default	Description
variant	variant	'info' | 'success' | 'warning' | 'danger'	'info'	Visual style variant determining the alert's color scheme and semantic meaning.
emphasis	emphasis	'solid' | 'soft' | 'outlined' | 'tinted'	'tinted'	Visual chrome weight on top of the role.
dismissible	dismissible	boolean	false	Whether the alert can be dismissed by the user. When true, a close button is displayed.
open	open	boolean	false	Whether the alert is currently visible. Set to true to show the alert, 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	—	The alert's title: a short heading above the message, and the alert's accessible name. As hy-toast's.
variantLabel	variant-label	string | undefined	—	The visually hidden word read before the message, naming the alert'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 alert'	Accessible label for the dismiss button. Use for internationalization.

Events

Event	Detail	Description
show	—	Fired when the alert becomes visible (does NOT bubble). Detail: { source: HyVisibilitySource }
hide	—	Fired when the alert is hidden (does NOT bubble). Detail: { source: HyVisibilitySource }
request-close	—	Fired before hiding; cancelable to prevent close (does NOT bubble). Detail: { source: HyVisibilitySource }

Slots

Slot	Description
default	The main alert message content
action	Optional action buttons or links

CSS Parts

Part	Description
base	The alert'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-alert-radius-container-md	var(--hy-radius-container-md)	Border radius of the alert
--hy-alert-padding-container-sm	var(--hy-padding-container-sm)	Padding inside the alert
--hy-alert-gap-container-md	var(--hy-gap-container-md)	Gap between alert elements
--hy-alert-gap-container-sm	var(--hy-gap-container-sm)	Gap within content area
--hy-alert-gap-container-lg	var(--hy-gap-container-lg)	Gap around the title
--hy-alert-background-info-tinted-rest	var(--hy-background-info-tinted-rest)	One of the generated color hooks (paint/alert.mjs): --hy-alert[-<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-alert-action-background-info-soft-rest	var(--hy-background-info-soft-rest)	One of the slotted action's re-points: --hy-alert-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-alert-stroke-sm	var(--hy-stroke-sm)	Border width of the alert
--hy-alert-body-md-font-family	var(--hy-body-md-font-family)	Font family override for alert message
--hy-alert-icon-size-lg	var(--hy-icon-size-lg)	Size of the alert icon

Methods

show()

Shows the alert programmatically.

hide()

Hides the alert programmatically. Emits a cancelable request-close event first.

Parameters:

• source - How the close was triggered (for event detail)