Alert

Alert — a message that stays on the page: a state, a warning, a result.

Beta · Feedback and status · packages/css/src/components/alert.css · React on Base UI: @pepperui/alert

.pui-alert · tone --info --success --warning --danger · style --outline · __icon __body __title __description __close.

Alert — every size and every stateOpen in the workshop

Sizes across, states down.

What it is for

Tone: neutral, info, success, warning, danger — the tone picks the glyph
Style: soft (the status bg; icon, title and description in its fg) and outline (surface/page, border/default, the status solid on the icon)
Title and Description are text properties, each with a Has toggle; Has icon; Has close (a Lucide x — in code, a ghost icon Button)
No states: an alert is not interactive. Info is blue and so is the brand — on a blue-accent surface prefer neutral

Use when a message that must stay until the user acts or the state changes — a failed sync, a plan limit, a saved confirmation that should remain, a data warning above a table.

Do not use when it should disappear on its own (Toast); it blocks the page (Dialog); it is a one-line hint under a field (Field’s description or error); it decorates a paragraph.

Relates to Toast (transient), Dialog (blocking), Field (inline error), Badge (a one-word status), Empty (no data at all).

Anti-patterns red for a neutral note · an alert with no action and no close that stays forever · three alerts stacked · a title that repeats the description · yellow as text (the warning fg is yellow-600).

Keywords: alert, banner, notice, message, warning, error, success, info, callout

Figma — page Alert: Alert (10 variants)

shadcn: alert

The markup — copy this

The class, the parts, and nothing that is not in the package. The same block opens alert.css.

<div class="pui-alert pui-alert--success" role="status">
  <span class="pui-icon pui-alert__icon">…circle-check…</span>
  <div class="pui-alert__body"><p class="pui-alert__title">Deck published</p>
    <p class="pui-alert__description">Anyone with the link can open it.</p></div>
  <button class="pui-icon-button pui-icon-button--ghost pui-icon-button--small pui-alert__close" aria-label="Dismiss">…x…</button></div>

The modifiers

	What it is	Note
Tone	(none) neutral · --info · --success · --warning · --danger	the tone picks the glyph
Style	(none) soft · --outline	—
Parts	__icon (16) · __body · __title (14 Medium) · __description (14 Regular) · __close (a ghost icon button)	—

Accessibility — measured, not assumed

Every number here is measured on the rendered component: contrast (npm run contrast:render), the focus ring (npm run focus) and the keyboard (npm run keyboard). The floors are principle 12’s.

Contrast

ink on ground	reads	floor	the matrix calls it
`#1a6b36` on `#d4f2de`	5.48	4.5	Success badge (promised)	ok
`#634e0f` on `#fef9e9`	7.59	4.5	Warning badge (promised)	ok
`#544d4d` on `#ffffff`	8.24	4.5	text.muted on surface.page (promised)	ok
`#5b0e0d` on `#fce9e8`	11.86	4.5	Danger badge (promised)	ok
`#110e56` on `#e9e9fb`	14.34	4.5	Info badge (promised)	ok
`#0b0202` on `#f2f2f2`	18.32	4.5	text.default on surface.sunken (promised)	ok
`#0b0202` on `#ffffff`	20.51	4.5	text.default on surface.page (promised)	ok

7 distinct pair(s) rendered, 0 that axe calls a violation.

The focus ring

2 of 2 focus stop(s) in this block meet WCAG 2.4.13 on screen — the same crop screenshotted focused and unfocused, and the difference measured.

Keyboard

Nothing in this component claims an ARIA role with a keyboard contract; its controls are ordinary ones and the browser already gives them their keys.

Tab order across the whole library is document order over 344 stops, and Shift+Tab is its exact reverse — no keyboard trap anywhere (WCAG 2.1.2).