Alert

A message in the page, where it applies: a notice, a success, a warning or an error, with buttons and a close.

Installation

npx @yolkui/cli add alert

Tones

tone sets the icon and the colour of the icon and the text: neutral, info, success, warning or destructive. The alert itself stays a neutral card. Write the title so it says what happened without the colour.

Scheduled maintenance
The dashboard will be read-only on Sunday from 02:00 to 04:00 UTC.
Info:
A new version is ready
Reload the page to get it.
Success:
Payment received
A receipt is on its way to your email.

With buttons

AlertAction holds the buttons. One button sits at the end of the text; with layout="stacked" on the Alert they go under it, which suits two buttons. Use an outline Button for the main action and a ghost one for the second, both size sm.

Info:
A new version is ready
Restart to update. Your open work is saved first.

In a narrow place

When the alert itself is narrower than 384px, the button moves under the text by itself. It follows the alert's width, not the screen's, so an alert in a sidebar stacks on a wide screen too. layout="inline" or layout="stacked" fixes one of the two.

Info:
A new version is ready
Restart to update.
Info:
A new version is ready
Restart to update.

Tinted

emphasis="subtle" fills the whole alert with the tone's light colour and writes the text in its dark one. Use it for a message that has to be seen at once among cards and fields; the plain alert is the everyday one.

Scheduled maintenance
The dashboard will be read-only on Sunday from 02:00 to 04:00 UTC.
Info:
A new version is ready
Reload the page to get it.
Success:
Payment received
A receipt is on its way to your email.

Tinted, with buttons

A gray or a black button sits badly on a colour. So on a tinted alert use a secondary Button for the main action: inside it the button takes the alert's own colour, one step darker, a look it has only here. A ghost Button for the second action darkens the tint under the pointer the same way, and so does the close button.

Info:
A new version is ready
Restart to update. Your open work is saved first.

Closing it

AlertClose adds a × that hides the alert. Focus then goes to the next thing after the alert that can take it, so someone using the keyboard stays where they were; finalFocus on the Alert names another place. Left alone the alert stays closed only while it is on the page: a reload or a new page shows it again. To remember the choice, keep the state with open and onOpenChange and store it.

Success:
Your changes are saved

With a list

A list inside AlertDescription gets its bullets and spacing. Count the problems in the title, so the first words already say how much there is to fix.

A short message needs no title: AlertDescription alone is one line. A link in the text keeps the text's colour and is underlined.

Another icon, or none

icon replaces the tone's icon with yours, at the same 16px, and icon={false} leaves it out. An svg passed as a child of Alert works too. Without the icon the colour is the only thing that tells the tone at a glance, so let the title say it.

Info:
Dark mode is here
Turn it on under your profile settings.
You are viewing an archived project
Nothing here can be changed.

Right to left

Under dir="rtl" the icon moves to the right and the buttons to the left on their own. Translate toneLabel with the rest of the text.

معلومة:
إصدار جديد جاهز
أعد التشغيل للتحديث.

API

Every part takes className and the props of its element.

PropTypeWhat it does
toneneutral · info · success · warning · destructiveOn Alert: the icon and the colour. neutral by default.
emphasisplain · subtleOn Alert: a neutral card with the icon and the text in the tone's colour, or the whole alert tinted. plain by default.
layoutauto · inline · stackedOn Alert: AlertAction at the end of the text or under it. auto by default: at the end, and under it when the alert is narrower than 384px.
toneLabelstring · falseOn Alert: the word a screen reader hears first, "Info", "Success", "Warning" or "Error" by tone. A translation, or false for none.
iconnode · falseOn Alert: replaces the tone's icon, or leaves it out.
openbooleanOn Alert: whether it shows, when the page keeps the state.
defaultOpenbooleanOn Alert: whether it shows at first. true by default.
onOpenChange(open) => voidOn Alert: called when AlertClose is pressed.
finalFocusrefOn Alert: where focus goes when AlertClose closes it. By default the next element after the alert that can take focus, or the one before it.
variantdefault · destructiveOn Alert: the names other libraries use, mapped to neutral and destructive. tone wins.
AlertTitledivThe heading. render makes it a heading of the page's level, e.g. render={<h2 />}.
AlertDescriptiondivThe text. Takes paragraphs, lists and links.
AlertActiondivThe buttons.
AlertCloseButtonThe ×, named "Close"; aria-label translates it.

Accessibility

An alert that appears while someone is on the page is read aloud without taking focus.

  • warning and destructive are role="alert": a screen reader reads them at once, interrupting what it was saying. The other tones are role="status" and wait until it is idle. Pass role to change it; an alert that is already there when the page loads is not announced either way.
  • The tone is never the only sign: every tone has its own icon, and a screen reader hears it as a word before the text ("Error: Payment failed"), which toneLabel translates. The icon itself is hidden from screen readers. Write the title so it says what happened in words.
  • The close button is named "Close" and takes the usual focus outline. When it is pressed the alert leaves the page and focus moves to the next element after it that can take focus (the one before it when the alert is last), so a keyboard or screen reader user is not sent back to the top of the page. finalFocus picks another place.
  • Text keeps at least 4.5:1 in both themes, on the plain alert and on every tint, the buttons included.
  • An alert does not leave by itself. For a message that should, use a Toast; for a question that must be answered before going on, an Alert Dialog; for an error on one field, the field's own error text.