Alert
Preview appears after the next Storybook update.
<Alert>Review them before you publish.</Alert>When to use
Use it for
- A condition that affects what the user is doing here: a failed build, a protected branch, contrast warnings.
- Tone follows meaning: danger for failed or blocked, warning for needs attention, success for a finished task that changed this page, info for context, neutral when there is no judgement.
- Inside a form or card, above the content it is about.
- actionsPlacement inline for one short message and one action, like a banner saying which change you are viewing with Back to latest at the end of the line. It wraps under the text on a phone. Keep below for a title plus a longer description.
Not for
- Confirming an action the user just took (Copied, Saved): use a Toast.
- An error on one field: use the Field error under that control.
- A decision the user must make before continuing: use an AlertDialog.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
Publish failed
Title says what happened, description says what to do
Users scan the bold line and read on only when they need to act.
2 pull requests wait for review
Give the way out as an action
A button next to the problem saves a search through the page.
Stacking several alerts
Three alerts in a row read as noise. Merge them, or keep the most severe and link to the rest.
Danger for something that is not broken
Red trains people to ignore red. Use info or warning when nothing failed.
Accessibility
- Alerts that appear after load are announced: danger and warning with role="alert" (interrupts), the others with role="status" (polite).
- Alerts present when the page loads should use announce="off": a live region on load is either ignored or read twice.
- Every tone has its own icon and the text carries the meaning, so color is never the only signal (WCAG 1.4.1).
- The dismiss button is a named IconButton (dismissLabel, default "Dismiss"). Move focus to a sensible place after dismissing if the alert had focus.
- Feedback text and icon colors are checked against their tinted backgrounds in both themes.
Content guidelines
- Title: what happened, in a few words, no period: "Publish failed".
- Description: why, and what to do next, in one or two sentences.
- Name objects and numbers: "3 tokens fail contrast", not "Some issues were found".
- No apology, no blame, no exclamation marks.
From the code Generated from the component, not editable here.
Anatomy and tokens
Read from packages/react/src/components/Alert/Alert.module.css at build time. Every value is a token: open one to see its alias chain in both themes.
- Container
.alert - Info tone (default)
.info - Success tone
.success - Warning tone
.warning - Danger tone
.danger - Tone icon
.icon - Text column
.content - Title
.title - Description
.description - Actions
.actions - Inline actions: the message and its action on one line
.inline .content - Title and description, when actions are inline
.text - Inline actions: the message and its action on one line
.inline .actions - Dismiss button
.dismiss
Motion and interaction
Alert does not animate: its states change at once.
From the code Generated from the component, not editable here.
Props
Parsed from the TypeScript types in packages/react/src/components/Alert/Alert.tsx, so this table cannot drift from the code. It also accepts every native <div> attribute except title.
| Prop | Type | Default | Description |
|---|---|---|---|
tone | 'neutral' | 'info' | 'success' | 'warning' | 'danger' | 'info' | Meaning of the message. The icon and the text carry it too, never the color alone. Default `info`. |
title | ReactNode | none | Short summary in bold. Optional when the description is one short sentence. |
icon | LucideIcon | false | none | Replace the tone icon, or pass `false` to hide it. |
actions | ReactNode | none | Buttons or links, for example "Review changes". Keep to two. |
actionsPlacement | 'below' | 'inline' | 'below' | `below` (default): actions sit under the text. `inline`: on the same line as a short message, at its end, and under it when the line is too narrow (a phone). Use size sm buttons inline. |
onDismiss | () => void | none | Shows a dismiss button and calls this when it is pressed. |
dismissLabel | string | 'Dismiss' | Accessible name of the dismiss button. Default "Dismiss". |
announce | 'auto' | 'off' | 'auto' | How assistive tech hears the alert when it appears after page load. `auto` uses role="alert" (interrupts) for danger and warning and role="status" (polite) for the others; `off` renders static content with no live region, right for alerts present when the page loads. Default `auto`. |
Playground
Change the props and see the real Alert update. Controls are generated from the TypeScript props; nothing here changes the system.
<Alert
tone="warning"
announce="off"
title="3 tokens fail contrast"
>
Review them before you publish.
</Alert>Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open Alert in Storybook).
Embed Storybook stories here (7)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.
Info
Success
Warning
Danger
Dismissible
InlineAction
AllStates
From the code Generated from the component, not editable here.
Changelog
- New
Feedback: Alert (five tones, actions, dismiss, correct live region), Toast (ToastProvider and useToast with success, error, warning, info, promise, update and close), Progress (linear and circular, determinate and indeterminate), Skeleton, EmptyState, plus Spinner stories and guidance
v1.0.0, Nov 11, 2026