---
title: "StatusPill"
description: "A short label that says which of four levels of attention something needs. It is shown as a word, an icon and a colour together, never as a colour alone."
url: "https://opsinjs.pensievelabs.org/docs/components/status-pill"
source: "https://opsinjs.pensievelabs.org/docs/components/status-pill.md"
section: "Components"
status: "shipped"
kind: "component"
category: "health-data-display"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["chip", "status chip", "status badge", "status label", "traffic light"]
governedBy: ["two-colour-axes", "alerts", "high-stakes-moments", "safety-review", "trends"]
usedIn: ["alert-escalation", "result-disclosure", "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="status-pill"
  status="shipped"
  questions="[
  &#x22;When a pill's level changes on screen, what is announced and how urgently? The component mounts no live region today, on purpose.&#x22;,
  &#x22;Whether the pill's surface and boundary hold up under prefers-contrast: more and in forced colours; neither response lives in the token layer today.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="status-pill" unbuilt="false" importPath="@/components/ui/status-pill" dependencies="[&#x22;lucide-react&#x22;]" />

```tsx
import { StatusPill } from "@/components/ui/status-pill"
```

```tsx
<StatusPill status="attention" describes="Second example measurement" />
```

## Examples [#examples]

<ComponentPreview name="status-pill" />

### Scanning a column [#scanning-a-column]

Four rows, each graded by `status`, and exactly one `urgent`.

<ComponentPreview name="status-pill-in-a-list" kind="example" align="start" />

### Every size keeps the word [#every-size-keeps-the-word]

`size` sets the type step and padding and nothing else. `sm` and `md` label a status in
prose and lists, and `lg` matches a heading.

<ComponentPreview name="status-pill-sizes" kind="example" align="start" />

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

<WhenToUse
  use="[
  &#x22;Labelling one result, reading or item with the level of attention the product has assigned to it.&#x22;,
  &#x22;Making a status scannable in a list, a table or a grid, where reading each row in full is not realistic.&#x22;,
  &#x22;Summarising a surface whose status the reader would otherwise have to infer from its contents.&#x22;,
]"
  avoid="[
  { case: &#x22;The status needs explaining, or the reader needs to know what to do about it.&#x22;, instead: &#x22;care-card&#x22; },
  { case: &#x22;The status must interrupt what the reader is doing rather than wait to be noticed.&#x22;, instead: &#x22;alert-banner&#x22; },
  { case: &#x22;The label is a category, a source, a tag, a count or a release phase rather than a level of attention.&#x22;, instead: &#x22;badge&#x22; },
  { case: &#x22;You want to show where a value sits relative to a range, which is a position rather than a level.&#x22;, instead: &#x22;range-bar&#x22; },
  { case: &#x22;The message is informational and carries no clinical level at all.&#x22;, instead: &#x22;callout&#x22; },
]"
/>

## Clinical meaning [#clinical-meaning]

**Asserts.** That the product has assigned one of exactly four levels of attention to
the thing the pill labels: `steady`, `watch`, `attention` or `urgent`, defined in
[Two colour axes](../health/two-colour-axes.mdx). It does not say what is wrong, why,
or what happens next.

**Never read as.** A diagnosis, a severity score or a triage category. The levels
describe what the interface asks of the reader, not the state of their body, so
`urgent` on a screen is not `urgent` in a clinical handover.

**Colour axis.** Status only, and never alone: every pill renders a word and a glyph
beside its colour. A category colour belongs on a [Badge](./badge.mdx), never on a pill,
and [Two colour axes](../health/two-colour-axes.mdx) says why the two never share an element.

**Thresholds.** None. The consuming product assigns the level from rules or a clinician,
and the pill derives nothing.

<SafetyCallout severity="urgent" evidence="opinion">
  At most one `urgent` pill may be visible on a screen. If the product's rules produce
  two, the screen needs an [AlertBanner](./alert-banner.mdx) for the most serious one.
  See [Alerts](../health/alerts.mdx).
</SafetyCallout>

## Accessibility [#accessibility]

The icon is `aria-hidden` and sized in `em`, so the word carries the meaning and the
glyph grows with it. At 200% text the pill grows and wraps, and the word is never
truncated or replaced by the icon alone. The pill is an enamel plate, the same in both
themes: white on the deep Steady, Needs attention and Urgent plates, deep brown on the
gold Watch plate. Every plate's word clears the body-text floor on its face and on the lit
band along its top, the build refuses a plate that does not, and the report below
measures both pairs. There is no axe, target-size, focus or 320px reflow failure.

`pnpm run check:a11y` checks on every commit that no file paints a status colour
without reading `CLINICAL_STATUS_META` and a glyph, that every status surface carries
`data-status`, and that status words come from `CLINICAL_STATUS_META[level].word`, never
a literal. The four levels name four distinct glyphs: circle, ringed dot, diamond and
octagon, the last two filled so each silhouette is heavier than the one below it. A11Y017
fails the build when two levels share one. The glyph takes the word's colour.

**Residual items.**

* The consuming product must pass `describes` when the pill floats free of its subject,
  in a table cell reached by column navigation or a card corner, because the component
  cannot know the reading context.
* With `describes`, the pill announces as *Needs attention, Second example measurement*.
  Omit it when the subject is visible text in the same reading unit.
* The pill is a `span`. One made into a filter is a Button and owes a Button's target
  and name.
* No live region is mounted, on purpose. A static read-only label is not a message, so
  a `role="status"` announcement would be wrong.
* Steady and Urgent are both deep plates with a white word, so in greyscale and under
  some colour-vision deficiencies they differ by word and glyph shape, not by colour.
* On paper the plate, its light and its shadow go, and the pill prints as the level's tint
  with its ink and a full-strength boundary. Forced colours drop the plate's light; that
  rendering is not measured. The boundary and the shadow are decorative and not measured.

<KeyboardTable
  name="status-pill"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Skips the pill&#x22;,
    notes: &#x22;Not focusable. A label with a tab stop is a stop every row pays for.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Skips the pill&#x22;,
    notes: &#x22;Same in reverse. Never in the focus order in either direction.&#x22;,
  },
]"
/>

<ContrastReport component="status-pill" />

## Props interface [#props-interface]

<PropsTable name="StatusPillProps" />

`status` has no default, and a value outside the four, including `unknown`, renders no
pill and warns in development. `className` is merged last and can strip the
fill or the line, so change `size` instead. It cannot recolour the word; a rule on
`[data-slot="status-pill"]` can.

### Data attributes [#data-attributes]

<DataAttributesTable
  name="status-pill"
  rows="[
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On the root and both inner parts, always&#x22;,
    value: &#x22;status-pill, status-pill-icon, status-pill-label&#x22;,
  },
  {
    attribute: &#x22;data-status&#x22;,
    condition: &#x22;On the root, always, because status is required&#x22;,
    value: &#x22;steady | watch | attention | urgent&#x22;,
  },
]"
/>
