Prototype Library

Alert Box

Inline status message with a variant-mapped icon, optional title, and optional dismiss control.

Inherited .astro import EsaAlertBox from '@esa/ecology/esa-alert-box.astro';

Preview

Heads up
This is an informational message. 
<AlertBox variant="info" title="Heads up">
  This is an informational message.
</AlertBox>

Variants

Heads up
This is an informational message.
Saved
Your changes were saved successfully.
Check this
Some fields need your attention.
Error
Something went wrong while saving. 
<AlertBox variant="info" title="Heads up">This is an informational message.</AlertBox>
<AlertBox variant="success" title="Saved">Your changes were saved successfully.</AlertBox>
<AlertBox variant="warning" title="Check this">Some fields need your attention.</AlertBox>
<AlertBox variant="danger" title="Error">Something went wrong while saving.</AlertBox>

States

The title is optional — omit it for a compact single-line alert. With dismissable, a close button appears and a dismissed event bubbles on click.

A compact, single-line alert with just a message.
Dismiss me
Click the × to hide this alert. 
<AlertBox variant="info">A compact, single-line alert with just a message.</AlertBox>
<AlertBox variant="warning" title="Dismiss me" dismissable={true}>Click the × to hide this alert.</AlertBox>

API

PropTypeDefaultDescription
variant 'info' | 'success' | 'warning' | 'danger' 'info' Tone — drives the background, border, and auto-mapped icon.
title string — Optional bold heading above the message.
dismissable boolean false Shows a close button that hides the alert and emits a dismissed event. Dismissing moves focus to the next focusable element after the box, rather than dropping it to the top of the document.
live boolean false Announce the box when it is injected into an already-loaded page. Off by default, and deliberately so — see Accessibility below. Ignored (with a console warning) when combined with dismissable, because a live region announces a button as bare text and gives no way to reach it.

Events

EventTypeDefaultDescription
dismissed CustomEvent — Bubbles when the close button is clicked (dismissable only).

Accessibility

It is not a live region, despite the name

An alert box is the component most likely to be injected at runtime, so making it role="alert" by default looks obvious. It is wrong for the general case, for three reasons that compound:

  • It takes a slot. Live regions announce raw text with no structure, so a slotted link or button is read as a run-on sentence with no roles. The component cannot see what you put in there.
  • dismissable puts a control inside it. A live region does not take focus and cannot be navigated to, so the user is told a button exists and given no route to it. A message with a control in it is a dialog — use esa-dialog.
  • Most alert boxes are present at page load, where there is no change for a live region to report — or worse, where some screen readers read it out on load as noise.

So live is opt-in. Turn it on only when all three hold: the box appears in response to something the user did, it is not dismissable, and its slot is plain text. danger then announces assertively (role="alert"); the other variants wait for a pause (role="status"). Combining live with dismissable is ignored and warns in the console.

Everything else

  • Icons are auto-mapped per variant (info / circle-check / triangle-alert / circle-alert) and marked aria-hidden.
  • The dismiss button has an aria-label="Dismiss".
  • Dismissing moves focus to the next focusable element after the box. Hiding the box removes the button that had focus, and without this focus falls to <body> — silently returning a keyboard user to the top of the document.