---
title: "AlertBanner"
description: "A message that appears at the top of a screen because something needs your attention now, saying what has happened and what to do about it."
url: "https://opsinjs.pensievelabs.org/docs/components/alert-banner"
source: "https://opsinjs.pensievelabs.org/docs/components/alert-banner.md"
section: "Components"
status: "shipped"
kind: "component"
category: "health-communication"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["warning", "notification", "alert", "banner", "warning banner", "notification banner", "inline alert"]
governedBy: ["two-colour-axes", "alerts", "high-stakes-moments", "safety-review"]
usedIn: ["alert-escalation", "offline-and-stale-data"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="alert-banner"
  status="shipped"
  questions="[
  &#x22;The budget of one urgent banner and two per screen is not enforced at runtime, because a banner only sees itself.&#x22;,
  &#x22;Nobody has listened in a screen reader: whether a heading survives navigation inside role=\&#x22;alert\&#x22;, and what in-place escalation announces, are untested.&#x22;,
  &#x22;`steady` is legal for de-escalation, yet a banner that can say nothing needs attention is one products will reach for to be noticed.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="alert-banner" unbuilt="false" importPath="@/components/ui/alert-banner" registryDependencies="[&#x22;status-pill&#x22;, &#x22;button&#x22;, &#x22;link&#x22;]" />

```tsx
import { AlertBanner } from "@/components/ui/alert-banner"
```

```tsx
<AlertBanner
  status="attention"
  heading="Your example measurement is outside the range your clinic set"
  detectedAt="2026-03-14T09:40:00+00:00"
  actions={[
    { label: "Contact your clinic", href: "/clinic" },
    { label: "See the reading and the range", href: "/results/example" },
  ]}
>
  Contact your clinic before your next appointment. This reading is outside the range they
  asked us to tell you about.
</AlertBanner>
```

## Examples [#examples]

<ComponentPreview name="alert-banner" />

The banner is a sheet tinted by its level. The recommended action is filled with the level's
own ink and labelled in its surface colour, the measured ink pair turned inside out, and the
second action and the dismiss control are outlined. All four levels take the same treatment.

### Two is the ceiling [#two-is-the-ceiling]

Two banners, the more serious first, because a reader meets them in DOM order.

<ComponentPreview name="alert-banner-two-is-the-ceiling" kind="example" align="start" />

### An urgent banner is acknowledged, not dismissed [#an-urgent-banner-is-acknowledged-not-dismissed]

`dismissible` renders nothing without `onAcknowledge`, which at `urgent` is the record, and
removing the banner drops focus to `<body>`, which the product must recover. One action,
because the route is same-day.

<ComponentPreview name="alert-banner-acknowledging-an-urgent-banner" kind="example" align="start" />

### `steady` is for de-escalation [#steady-is-for-de-escalation]

The one honest use of the quietest level: withdrawing an alert the product raised earlier.
No `actions`, because only `attention` and `urgent` require one.

<ComponentPreview name="alert-banner-steady-is-for-de-escalation" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Something has changed since the reader last looked, and they need to know before carrying on.&#x22;,
  &#x22;A reading has crossed a threshold the product owns, with a specific action attached.&#x22;,
  &#x22;A condition affects the whole screen: stale data, a disconnected device, an unfinished sync.&#x22;,
]"
  avoid="[
  { case: &#x22;Information the reader can take or leave, where nothing changes if they do not read it.&#x22;, instead: &#x22;callout&#x22; },
  { case: &#x22;The status belongs to one result, not the screen.&#x22;, instead: &#x22;status-pill&#x22; },
  { case: &#x22;The content is an instruction with steps and timing, not an announcement.&#x22;, instead: &#x22;care-card&#x22; },
  { case: &#x22;The reader must respond before anything else can happen.&#x22;, instead: &#x22;dialog&#x22; },
  { case: &#x22;Someone has disclosed thoughts of self-harm or suicide, which is not the status axis. See Crisis and self-harm.&#x22;, instead: &#x22;care-card&#x22; },
]"
/>

## Clinical meaning [#clinical-meaning]

**Asserts.** That the product has decided this screen needs the reader's attention at one
of four levels, with something specific to do at `attention` and `urgent`. The component
compares nothing: `status` is assigned from a range the product owns.

**Never read as.** A clinical judgement about the reader, an instruction from a person, or
a substitute for emergency services. A finding routed *stop and call for help now* leaves
the banner. See [High-stakes moments](../health/high-stakes-moments.mdx).

**Colour axis.** Status only, with no `category` prop, so a banner never carries category
colour. Urgency is never carried by motion either, and no transition ships. See
[Alerts](../health/alerts.mdx).

**Thresholds.** None. No staleness default and no number in the component. The level's
word comes from the composed [StatusPill](./status-pill.mdx), never from `heading`.

**Budget.** At most one `urgent` banner and two per screen, per
[Alerts](../health/alerts.mdx), and the component cannot count across a screen. No live
region mounts at `steady` or `watch`, a named departure from
[Two colour axes](../health/two-colour-axes.mdx) rule 9.

<SafetyCallout severity="urgent" evidence="opinion">
  An `urgent` banner must never be the only place a serious message appears, and never
  dismissible without an acknowledgement the product records.
</SafetyCallout>

## Accessibility [#accessibility]

Confirmed: colour never carries meaning alone, because the word and glyph come from the
composed [StatusPill](./status-pill.mdx) and shape and position separate the levels. The
live region wraps only the heading and body, `role="alert"` at `urgent` and
`aria-live="polite"` with `aria-atomic` at `attention`. Focus never moves, every control
clears the 44pt floor, axe and focus-visible checks were clean, and the audit changed
nothing.

**Residual items.**

* At `steady` and `watch` no live region mounts, so a de-escalation banner inserted after
  a condition resolves is not announced to a reader already on the page. That is a
  deliberate departure from [Two colour axes](../health/two-colour-axes.mdx) rule 9 on
  alarm-fatigue grounds, a doctrine call left for a human reviewer.
* Escalating in place relies on the caller passing `key={status}` to remount, which the
  component cannot enforce.
* Still ungated: any real screen reader, `forced-colors`, and the root's missing
  accessible name.

<KeyboardTable
  name="alert-banner"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves through the actions, then dismiss&#x22;,
    notes: &#x22;The banner itself is not a tab stop.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;The same in reverse&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Follows a link action or activates a button&#x22;,
    notes: &#x22;href renders an anchor, onSelect a real button.&#x22;,
  },
  {
    keys: &#x22;Space&#x22;,
    action: &#x22;Activates a button action or the dismiss&#x22;,
    notes: &#x22;On a link action Space scrolls the page.&#x22;,
  },
  {
    keys: &#x22;Escape&#x22;,
    action: &#x22;Nothing&#x22;,
    notes: &#x22;The dismiss control is the only way out.&#x22;,
  },
]"
/>

<ContrastReport component="alert-banner" />

## Props interface [#props-interface]

<PropsTable name="AlertBannerProps" />

A `status` outside the four levels renders nothing and reports OPSIN-0021 (OPSIN-0011 for
`unknown`). `heading` names the subject, because the component renders the level's word.
`headingLevel` outside 2 to 6 falls back to `h2`. A third action renders and is reported.
`dismissible` needs `onAcknowledge` at every level. `now`, `locale` and `timeZone` render
nothing. `AlertAction` is also exported:

```ts
export interface AlertAction {
  label: string
  href?: string
  onSelect?: () => void
  recommended?: boolean
}
```

### Data attributes [#data-attributes]

<DataAttributesTable
  name="alert-banner"
  rows="[
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On the root, always&#x22;,
    value: &#x22;alert-banner&#x22;,
  },
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On inner parts&#x22;,
    value: &#x22;alert-banner-announcement, -heading, -heading-text, -body, -actions, -action, -dismiss&#x22;,
  },
  {
    attribute: &#x22;data-status&#x22;,
    condition: &#x22;On the root, always&#x22;,
    value: &#x22;steady | watch | attention | urgent&#x22;,
  },
  {
    attribute: &#x22;data-detected-at&#x22;,
    condition: &#x22;On the root, when detectedAt is non-empty&#x22;,
    value: &#x22;The ISO 8601 instant, verbatim. Absent otherwise.&#x22;,
  },
]"
/>
