Alert
An in-flow message that reports the result of an action where the traveller is already looking, and stays until they have seen it.
Installation
npx shadcn@latest add @flyingsalmon/alertUsage
import {
Alert,
AlertDescription,
AlertTitle,
AlertVariant,
} from '@/components/ui/alert'
export function AlertUsage() {
return (
<Alert variant={AlertVariant.Success}>
<AlertTitle>Trip saved</AlertTitle>
<AlertDescription>Six days in Lisbon, ready to share.</AlertDescription>
</Alert>
)
}Examples
Variants
Info is the default, then success, warning, and error. The card and its border stay plain, and the icon alone carries the variant, so an alert reads as a message on the page and never as a coloured block.
Sizes
Small tightens the padding and the icon for an alert inside a dense surface. The text size does not change: a message does not shrink its type.
Title and description
The title is optional; a short message works on its own. When both are present the description steps back to the muted colour, so the title is read first.
Custom icon
Pass icon to replace the variant icon, or null to drop it. The alert sizes and colours whatever node you pass.
Dismissible
Pass onClose and the alert shows a Dismiss button. The alert never hides itself: it calls onClose and your app decides what happens, so the app can retry or keep the message until the traveller has seen it.
With actions
Put the buttons in the children, under the description. Two at most, one outline and one ghost, both small. A third action means the message belongs somewhere bigger than an alert.
Open and close
open grows the alert in and shrinks it out. The alert carries its own exit, so you toggle open and write no motion code.
In a form's result slot
Submit the form. The button shows its own busyness, then the failure appears below the actions row, where the traveller is already looking, with their input kept.
Guidelines
When to use
- To report the result of a form submit, in the form’s result slot below the actions row.
- To show a warning or notice that belongs to a region of the page and should sit in the flow beside it.
When not to use
- Use Notice for a result with no visible home, such as the outcome of a dialog form that has already closed. A notice stays on screen and links back to its subject.
- Use Error state when a region failed to load. The region itself says so, with a retry.
- Use Fields for the error on a single field. The field shows its own error beside its input.
Do and don’t
- DoPlace the alert where the traveller is already looking, and keep it until they have seen it.A message that appears elsewhere or disappears on a timer is missed, and a missed failure looks like a success.
- DoPick the variant by what the traveller must do: error for a failure, warning for something to check, success and info for the rest.The colour and icon tell the traveller whether to stop, check, or carry on before they read a word.
- DoWrite the title as what happened, in a sentence, and the description as what to do next or what was kept. Put the way forward inside the alert as a link or a button.The traveller reads the fact, then finds the next step without leaving the message.
- DoShow a standing condition, such as trips saved only in this browser, as a warning at the top of the page with its action inside.It stays true until the traveller acts, so it sits where every visit starts.
- Don’tLet an alert vanish on a timer. It goes when the traveller closes it or the state it reports ends.A message that removes itself cannot be read at the traveller’s pace.
- Don’tStack several alerts for one result.Several messages for one result make the traveller work out which one matters. Write one alert that says it. A separate condition, such as each day that clashes, gets its own.
Accessibility
| Key | Description |
|---|---|
| Tab | Moves focus to the Dismiss button when onClose is passed, after any action buttons in the body. Without onClose the alert has no tab stop. |
| EnterSpace | On the Dismiss button, calls onClose. |
An error alert has role="alert", so a screen reader interrupts with it. The other three variants have role="status" and wait their turn. Pass role to override the mapping. The icon is hidden from assistive technology, so the message is announced once.
The alert does no focus management. When you remove an alert whose Dismiss button holds focus, send focus back to the control that produced it.
API
Alert
Also takes every <div> attribute. AlertTitle and AlertDescription take only their element’s props.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | AlertVariant | AlertVariant.Info | Info, Success, Warning, or Error. Error interrupts a screen reader; the others wait their turn. |
| size | AlertSize | AlertSize.Default | Default or Small. The text size is the same in both. |
| icon | ReactNode | – | Replaces the variant icon. Pass null to show no icon. |
| onClose | () => void | – | Shows a Dismiss button that calls it. The alert does not hide itself: your app owns its lifecycle and sets open or removes it. |
| open | boolean | true | Shows or hides the alert, animating the change. |
| animateOpen | boolean | true | Set false to skip the height animation. |
| role | string | – | Overrides the role the variant sets: alert for error, status for the rest. |