Alert

An alert is a sentence about something already on the screen: a summary above the fields it names, the step of a checkout that failed, a notice that applies to the whole panel. It stays in the flow beside its subject, so the connection between the message and the thing it describes is spatial as well as announced.

That is what separates it from its siblings. A toast reports what the reader has just done and then leaves; an alert stays where you put it and describes the state of what is next to it. Where a skeleton or loading-state claims a region and fills it, an alert annotates one that is already there.

Usage

import { Alert } from "@asheeui/web";

<Alert type="error" title="Payment failed">
  The card was declined. Check the details and try again.
</Alert>

title is the claim, one line, read first, and children is the sentence that explains it or says what to do next. Both are optional: a title alone is a statement, a body alone is a message without a headline, and the component does not invent one for you.

Intents

type is the alert's intent, and it decides two things at once: the colour role the surface takes, info is the primary role, success is success, warning is warning and error is danger, and how urgently the message is announced. error and warning interrupt the reader; info and success wait for a pause. Colour and volume are one decision rather than two, so a screenshot and a screen reader agree about what matters.

icon replaces the leading affordance with a node of your own, which is how a product with its own icon set keeps it, the slot is decoration either way.

Dismissing

isClosable asks for the dismiss control and onClose supplies the behaviour; the control renders only when both are given, because a button that dismisses nothing is a worse affordance than no button. The alert never removes itself, so onClose is where you set the state, which is what lets the demo below put a dismissed notice back.

closeLabel names the control, defaulting to Dismiss alert. State it whenever a page can show two closeable alerts, so a reader listing the page's controls can tell them apart.

A dismissible alert suits a notice the reader has finished with. A validation summary should not be dismissible: dismissing it destroys the list of what is wrong.

Props

type is registered as info and radius as md, so both answer from the instance, then from components.alert, then from the framework's fallback. variant is deliberately not registered: it resolves from the application's defaultVariant, and because a message surface has no underline treatment, a global default of underlined resolves to bordered rather than drawing an alert as a rule under a line of text. title, children, icon, isClosable, onClose, closeLabel and role are instance-only, because they state this message rather than the design.

Registering radius has one consequence worth knowing: the application's defaultRadius does not reach an alert. A product that rounds every other surface still gets md alerts until it states components.alert.radius, which is the one place to change them all.

Accessibility

• The intent chooses the live region: error and warning render role="alert", which interrupts, while info and success render role="status", which waits its turn. Pass role when the situation should decide the volume rather than the wording, an info message that answers the reader's press can deserve role="alert", and a condition that was on the page before they arrived does not need to interrupt anyone.
• A live region announces a change, not a presence. An alert in the page's first markup is silent: it is read when the reader reaches it, which is the right behaviour for a notice that did not just happen.
• The dismiss control is a real <button type="button"> named by closeLabel, so Tab reaches it and Enter or Space presses it. It is the only focusable element the component adds, and the alert never moves focus into itself. If onClose removes the alert, its control goes with it, so move focus wherever the reader should land next.
• The leading icon is aria-hidden, including an icon you supply: the message text carries the information, and the glyph only repeats it.

The two channels, which surface uses which, and why some feedback is deliberately silent are described in Announcements.

Related