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 alertTones
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.
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.
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.
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.
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.
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.
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.
One line, with a link
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.
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.
| Prop | Type | What it does |
|---|---|---|
tone | neutral · info · success · warning · destructive | On Alert: the icon and the colour. neutral by default. |
emphasis | plain · subtle | On Alert: a neutral card with the icon and the text in the tone's colour, or the whole alert tinted. plain by default. |
layout | auto · inline · stacked | On 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. |
toneLabel | string · false | On Alert: the word a screen reader hears first, "Info", "Success", "Warning" or "Error" by tone. A translation, or false for none. |
icon | node · false | On Alert: replaces the tone's icon, or leaves it out. |
open | boolean | On Alert: whether it shows, when the page keeps the state. |
defaultOpen | boolean | On Alert: whether it shows at first. true by default. |
onOpenChange | (open) => void | On Alert: called when AlertClose is pressed. |
finalFocus | ref | On 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. |
variant | default · destructive | On Alert: the names other libraries use, mapped to neutral and destructive. tone wins. |
AlertTitle | div | The heading. render makes it a heading of the page's level, e.g. render={<h2 />}. |
AlertDescription | div | The text. Takes paragraphs, lists and links. |
AlertAction | div | The buttons. |
AlertClose | Button | The ×, 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.