---
title: "MetricTile"
description: "A compact readout of one measurement. It carries the number, its unit and how recent it is, and it is sized to sit in a grid with several others."
url: "https://opsinjs.pensievelabs.org/docs/components/metric-tile"
source: "https://opsinjs.pensievelabs.org/docs/components/metric-tile.md"
section: "Components"
status: "shipped"
kind: "component"
category: "health-data-display"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["stat", "kpi", "tile", "vitals", "resting heart rate", "spo2", "summary tile", "steps"]
governedBy: ["two-colour-axes", "health/index", "trends", "numbers", "consent-and-privacy", "reference-ranges"]
usedIn: ["alert-escalation", "empty-and-first-use", "result-disclosure", "offline-and-stale-data", "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="metric-tile"
  status="shipped"
  questions="[
  &#x22;There is no mask, no reveal and no sensitivity prop, and Value owns the digits and has none either.&#x22;,
  &#x22;event names when a reading happened, never where it came from, so a device estimate and a laboratory result sound alike, with no provenance prop.&#x22;,
  &#x22;The instant rule and the staleness verdict are computed here and again inside RelativeTime, and only a reader keeps the two in step.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="metric-tile" unbuilt="false" importPath="@/components/ui/metric-tile" registryDependencies="[&#x22;surface&#x22;, &#x22;value&#x22;, &#x22;status-pill&#x22;, &#x22;relative-time&#x22;]" />

```tsx
import { MetricTile } from "@/components/ui/metric-tile"
```

```tsx
<MetricTile
  label="Example measurement"
  value={14}
  unit="steps"
  precision={0}
  measuredAt="2026-04-06T07:15:00+00:00"
  now={now}
  href="/results/example"
/>
```

## Examples [#examples]

<ComponentPreview name="metric-tile" />

### A summary grid [#a-summary-grid]

Every tint is category. Exactly one tile carries a `status`, as a pill with the word in
it, and the others say nothing about urgency.

<ComponentPreview name="metric-tile-a-summary-grid" kind="example" align="start" />

### No boundary was supplied [#no-boundary-was-supplied]

Two readings, three hours and five weeks old, with no `staleAfterHours`. Only the printed
date marks the older one.

<ComponentPreview name="metric-tile-no-boundary-supplied" kind="example" align="start" />

### States [#states]

| Data state | What MetricTile renders                                                                 |
| ---------- | --------------------------------------------------------------------------------------- |
| Error      | A `measuredAt` the tile cannot locate beside a reading is refused, and nothing renders. |
| Empty      | `value={null}` keeps the label, drops the time line, and is not zero.                   |
| Stale      | Past `staleAfterHours` the parts mute and the time line adds *may be out of date*.      |

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

<WhenToUse
  use="[
  &#x22;A summary grid where several measurements are visible at once and the reader scans.&#x22;,
  &#x22;A measurement the reader already understands, such as their resting heart rate.&#x22;,
  &#x22;An entry point: a tile that opens the full result via href.&#x22;,
]"
  avoid="[
  { case: &#x22;The reader is seeing this measurement for the first time and needs it explained.&#x22;, instead: &#x22;result-card&#x22; },
  { case: &#x22;The value only makes sense against a reference range that will not fit.&#x22;, instead: &#x22;range-bar&#x22; },
  { case: &#x22;A whole surface has no reading yet. One empty cell in a grid is still a tile.&#x22;, instead: &#x22;empty-state&#x22; },
  { case: &#x22;You need to show how the value has moved. This draws no line.&#x22;, instead: &#x22;trend-sparkline&#x22; },
  { case: &#x22;The value is still loading and the grid would otherwise reflow.&#x22;, instead: &#x22;skeleton&#x22; },
]"
/>

## Clinical meaning [#clinical-meaning]

**Asserts.** With a reading, that this measurement had this value, in this unit, at
this time, so `measuredAt` is required beside one. An absence is not a reading of zero.

**Never read as.** A current reading, unless it is one. Past the product's boundary the
tile mutes and says so in words, as
[Trends and uncertainty](../health/trends.mdx) requires.

**Colour axis.** Category, on the icon and the label only. Status appears as an embedded
[StatusPill](./status-pill.mdx), never the tile's background, so no element carries
both ([Two colour axes](../health/two-colour-axes.mdx)).

**Thresholds.** None. `staleAfterHours` has no default, because opsinjs holds no boundary
for any measurement, and omitting it means no stale treatment. The tile derives no level,
because `status` is the product's under [Two colour axes](../health/two-colour-axes.mdx).
Pair `attention` or `urgent` with an `href`, because nothing here enforces it.

**Provenance and masking.** There is no provenance prop and no mask, so do not route a
figure nobody measured through `measuredAt`.
[Trends and uncertainty](../health/trends.mdx) and
[Consent and privacy](../health/consent-and-privacy.mdx) name this component, and neither is met.

## Accessibility [#accessibility]

The rendered pass found no axe violation, target-size hit, `focus-visible` failure or
reflow at 320px, and the source needed no fix. A linked tile sinks to 0.98 when pressed
and comes back with no spring, so its reading is never drawn past its true size.

**Residual items.**

* `Value` speaks *kilograms* for a visible *kg*, so a linked tile can trip WCAG 2.5.3
  Label in Name. The repair belongs in `Value` and is deferred, and the *steps* demo does
  not trip.
* Nothing enforces the JSDoc rule that `attention` and `urgent` pair with an `href`.
* Contrast as the tile composes it, `prefers-contrast: more`, `forced-colors`, 200% text,
  print and masking are unverified.

<KeyboardTable
  name="metric-tile"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves to the tile, when it has an href&#x22;,
    notes: &#x22;One stop for the whole tile, none without an href.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves backwards to the tile&#x22;,
    notes: &#x22;DOM order is visual order.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Follows the link&#x22;,
    notes: &#x22;Only when href is set.&#x22;,
  },
  {
    keys: &#x22;Space&#x22;,
    action: &#x22;Scrolls the page&#x22;,
    notes: &#x22;A link does not activate on Space.&#x22;,
  },
]"
/>

<ContrastReport component="metric-tile" />

## Props interface [#props-interface]

<PropsTable name="MetricTileProps" />

A `measuredAt` the tile cannot locate beside a reading renders nothing, and development
reports it once. `label`, `value`, `measuredAt`, `now` and `precision` are required with
no default. `value` is `number | null`, so a compound reading takes two
tiles. Read `now` once per screen and pass it to every tile.

### Data attributes [#data-attributes]

<DataAttributesTable
  name="metric-tile"
  rows="[
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On the root and every part; icon, affordance and time only when rendered&#x22;,
    value: &#x22;metric-tile, metric-tile-header, metric-tile-icon, metric-tile-label, metric-tile-affordance, metric-tile-reading, metric-tile-time&#x22;,
  },
  {
    attribute: &#x22;data-category&#x22;,
    condition: &#x22;On the icon and the label only, when a known category is passed&#x22;,
    value: &#x22;sleep | heart | activity | nutrition | mind | labs&#x22;,
  },
  {
    attribute: &#x22;data-status&#x22;,
    condition: &#x22;On the embedded StatusPill only, when a status is set. The tile stamps none&#x22;,
    value: &#x22;steady | watch | attention | urgent&#x22;,
  },
  {
    attribute: &#x22;data-opsinjs-value&#x22;,
    condition: &#x22;On the embedded Value, always&#x22;,
    value: &#x22;The unrounded number, or an empty string with no reading&#x22;,
  },
]"
/>
