---
title: "RangeLegend"
description: "The key naming the tones a RangeBar draws, so a reader learns in one place what the reference band and each status colour mean. It asserts nothing itself."
url: "https://opsinjs.pensievelabs.org/docs/components/range-legend"
source: "https://opsinjs.pensievelabs.org/docs/components/range-legend.md"
section: "Components"
status: "shipped"
kind: "component"
category: "health-data-display"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["key", "chart legend", "band legend"]
governedBy: ["reference-ranges", "two-colour-axes"]
usedIn: ["trend-review"]
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="range-legend"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured, and every swatch and glyph is painted on the host's ground rather than a surface the token contract tunes against.&#x22;,
  &#x22;The binding to a RangeBar is a convention rather than a gate, so nothing in the code stops a caller placing the legend away from its bars.&#x22;,
  &#x22;No screen reader user has been asked whether a list of aria-hidden swatches with text labels reads usefully, or whether it needs an accessible name pointing at its bar.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

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

```tsx
import { RangeLegend } from "@/components/ui/range-legend"
```

```tsx
<RangeLegend
  bands={[
    { label: "The usual range", description: "From your laboratory. Most results sit here." },
    { label: "Worth watching", tone: "watch" },
    { label: "Needs attention", tone: "attention" },
  ]}
/>
```

## Examples [#examples]

<ComponentPreview name="range-legend" />

### The legend beside its bar [#the-legend-beside-its-bar]

The same container as the bars it names, `bands` holding the tones they draw. Each swatch is a miniature of the bar's own piece: the lit band in the tube, or the cursor with its index line.

<ComponentPreview name="range-legend-beside-its-bar" kind="example" align="start" />

### The four levels, named once [#the-four-levels-named-once]

The whole vocabulary in one key: the neutral band and four status levels, each row's `tone` giving its word, glyph and colour.

<ComponentPreview name="range-legend-the-four-levels" kind="example" align="start" />

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

<WhenToUse
  use="[
  &#x22;Beside RangeBars that share a status vocabulary, naming each level once instead of a pill per row.&#x22;,
  &#x22;As the key beneath a single RangeBar whose status tones a first time reader has not met.&#x22;,
  &#x22;Wherever a reader must learn the neutral band and the status colours before reading the numbers.&#x22;,
]"
  avoid="[
  { case: &#x22;You are showing one measurement against its range; the bar already states reading, range and position.&#x22;, instead: &#x22;range-bar&#x22; },
  { case: &#x22;You want the level of one reading. A legend names the vocabulary, never a verdict.&#x22;, instead: &#x22;status-pill&#x22; },
  { case: &#x22;You are explaining a single clinical term rather than a set of tones.&#x22;, instead: &#x22;term&#x22; },
]"
/>

## Clinical meaning [#clinical-meaning]

**Asserts.** The tones the bar beside it draws, and what each one means. Nothing about any reading, cause or next step.

**Never read as.** A scale, a diagnosis or a verdict on the reader. "Needs attention" names a tone a product may assign, not the reader's result. "Normal" and "abnormal" are banned; [Reference ranges](../health/reference-ranges.mdx) carries the list.

**Colour axis.** The status axis and the neutral reference range band only. No element carries `data-category`, because [Two colour axes](../health/two-colour-axes.mdx) never mix. Every status row draws fill, glyph and word together, so the level survives greyscale.

**Thresholds.** The product owns every word, range and level. RangeLegend ships no band names; words arrive as props and the swatch colours are all it supplies.

## Accessibility [#accessibility]

Each swatch and glyph carries `aria-hidden`, so a screen reader skips the decoration. No element carries both `data-category` and `data-status`, and this file writes no category colour. Nothing takes focus, answers a key or animates, so `prefers-reduced-motion` has no state to reduce. At 200% text the swatches grow with the words, which wrap with no ellipsis, and under `forced-colors: active` the tube keeps a `CanvasText` outline and a status swatch's index line takes `Highlight`.

The audit fixed two gaps. The legend `<ul>` had no accessible name, and optional `aria-label` and `aria-labelledby` props now forward onto the root, so a caller names the key or points it at the bar's heading. A blank status label would draw colour and glyph with no word, a colour-alone failure, and a guard now warns on it, with the empty-bands and invalid-tone guards.

**Residual items.**

* A status swatch's index line takes RangeBar's tick tone, the level's line role, inside a glass cursor, so its contrast against the cursor is unmeasured. Each is `aria-hidden` decoration redundant to the word and glyph, so a low-contrast swatch loses nothing, and measuring the four lines and the neutral border in light and dark is a recommended enhancement.
* Label and description use the foreground and muted-foreground role tokens, not re-measured in this pass.
* The legend cannot enforce in code that it sits beside its bar. `aria-labelledby` is how a caller binds it, and the audit cannot verify callers do.

<KeyboardTable
  name="range-legend"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Skips the whole component&#x22;,
    notes: &#x22;Nothing here is focusable.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Skips the whole component&#x22;,
    notes: &#x22;Never in the focus order.&#x22;,
  },
  {
    keys: &#x22;Arrow keys&#x22;,
    action: &#x22;Nothing&#x22;,
    notes: &#x22;Swatches are decorative, words static.&#x22;,
  },
]"
/>

<ContrastReport component="range-legend" />

## Props interface [#props-interface]

<PropsTable name="RangeLegendProps" />

`tone` is typed to the four `ClinicalStatus` levels in [Two colour axes](../health/two-colour-axes.mdx). A value outside the four is refused with a development warning and falls back to the neutral band. An empty `bands` array renders nothing and warns in development.

### Data attributes [#data-attributes]

<DataAttributesTable
  name="range-legend"
  rows="[
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On the root and every named inner part, always&#x22;,
    value: &#x22;range-legend, range-legend-item, range-legend-swatch, range-legend-label&#x22;,
  },
  {
    attribute: &#x22;data-status&#x22;,
    condition: &#x22;On a status row's item; absent on the neutral band row&#x22;,
    value: &#x22;The row's tone: steady, watch, attention or urgent&#x22;,
  },
]"
/>
