Components · Messaging
Banner Alert
An inline message about something that just happened or something the user needs to know. The only dialog in the set that does not interrupt — it appears in the flow of the page.
Figma source: Banner Alert ↗Examples
<!-- Success and information: role="status" — announced politely -->
<div class="cds-banner cds-banner--success" role="status">
<span class="cds-banner__icon" aria-hidden="true" class="fa fa-check"></span>
<div class="cds-banner__body">Proposal 24-0117 was submitted for review.</div>
<button type="button" class="cds-banner__dismiss" aria-label="Dismiss message">✕</button>
</div>
<!-- Errors: role="alert" — interrupts, because it must be noticed -->
<div class="cds-banner cds-banner--error" role="alert">
<div class="cds-banner__body">Three required fields are incomplete.</div>
</div>Figma properties
| Property | Values | Notes |
|---|---|---|
Type | Success · Error · Warning · Neutral | Determines colour and icon. (The Figma variant is spelled “Nuetral”.) |
<Type> Alert Message | text | One text property per type. |
The artboard note: “Alert message should describe to the user the reason for the alert — select alert type based on alert usage.”
The Dialogs pattern breaks a dialog into header, content and actions. The Banner Alert annotation points out that it collapses two of those: “the message acts as a header, but also as the content, as the conversation with the user is one way.”
Which is why the message has to carry everything on its own. “An error occurred” uses the whole component to say nothing.
Dismissal
The Figma page compares three real products, and the comparison is the guidance:
| Example | Behaviour | When it fits |
|---|---|---|
| Gmail — after sending | Auto-dismisses, with a manual dismiss available | Confirmation of a routine action the user expects to succeed |
| Nextdoor — unsubscribe | Auto-dismisses, no manual dismiss | Low-stakes confirmation where the message is glanceable |
| Chase — signed out | Auto-dismisses, with manual dismiss | Confirmation the user may want to read twice |
When to use it
- Auto-dismiss success messages after 5–8 seconds, and offer manual dismissal too.
- Keep error messages until the user dismisses them or fixes the problem.
- Keep neutral state messages — “read-only while under review” — for as long as the state holds, with no dismiss at all.
- Place the banner where the action happened: at the top of the form it concerns, not the top of the browser.
When not to use it
- Do not auto-dismiss an error. If it mattered enough to interrupt, it matters enough to stay.
- Do not stack more than one banner; combine the messages.
- Do not use a banner for something requiring a decision — that is a Confirmation Alert.
- Do not let a dismissed banner be the only record of a failure.
Accessibility
role="alert"for errors — it interrupts the screen reader, which is correct when the user needs to know now.role="status"for success, warning and neutral — announced at the next natural pause, without cutting the user off.- The banner must be in the DOM when its role fires. Injecting an element that already
has
role="alert"is unreliable; render the container first, then set the text. - Icons are decorative; the text carries the message. Colour plus icon plus text means three signals, none of which is colour alone.
- The dismiss button needs a label, and focus must go somewhere sensible after dismissal.
Tokens consumed
| Token | Applied to | Resolves to |
|---|---|---|
--success-background / --success-border / --success-text | Success variant | green-100 / green-500 / green-500 |
--error-background / --error-border / --error-text | Error variant | red-100 / red-500 / red-500 |
--color-yellow-200 / --color-yellow-300 / --color-yellow-100 | Warning variant | Reaches past the semantic layer — warning has no semantic tokens yet |
--color-gray-100 / --color-gray-300 | Neutral variant | gray-100 / gray-300 |
--border-width-3 | Left edge | 3px |