---
title: "Offline and stale data"
description: "What a health screen shows when it cannot vouch for its numbers. The value stays, and every claim about now is withdrawn."
url: "https://opsinjs.pensievelabs.org/docs/patterns/offline-and-stale-data"
source: "https://opsinjs.pensievelabs.org/docs/patterns/offline-and-stale-data.md"
section: "Patterns"
kind: "pattern"
aliases: ["offline mode", "stale readings screen", "last synced", "cached readings", "no connection"]
---

Staleness degrades assertions, not values. The number stays, because the reader is entitled to it. Its status, trend, range comparison and alerts are claims about now, which the product no longer knows.

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

Use it when the product shows a value it can no longer stand behind, because the network is gone, a device has not synced or a refresh failed.

Do not use it when:

* There is no value at all. That is [Empty and first use](./empty-and-first-use.mdx).
* The value is old by design. A March blood test is dated, not stale, so show its date.

[Trends and uncertainty](../health/trends.mdx) holds the doctrine on staleness and provenance.

## How it works [#how-it-works]

1. Every measure has a freshness window, set by the team that owns its thresholds.
2. Beyond the window, keep the value and its timestamp and withdraw the status axis: no [StatusPill](../components/status-pill.mdx), no colour-coded verdict, no trend arrow.
3. Suspend alerts computed from stale data rather than firing them. See [Alert escalation](./alert-escalation.mdx).
4. Refresh quietly. Success restores full assertions without a banner. Failure says what being offline means here.
5. Show an offline entry at once, marked unsynced, with the time it was made.
6. Show conflicts and never merge them. Two devices writing one slot make two entries the reader resolves.

| State           | Status axis              | Timestamp                              |
| --------------- | ------------------------ | -------------------------------------- |
| Fresh           | Full                     | De-emphasised                          |
| Ageing          | Full                     | Visible, age promoted                  |
| Stale           | Withdrawn                | Prominent                              |
| Offline, cached | Withdrawn                | Prominent, with an offline notice      |
| Unsynced write  | None yet                 | Time of entry, marked unsynced         |
| Conflict        | Withdrawn until resolved | Both times shown                       |
| Unknown age     | Withdrawn                | "We don't know when this was measured" |

The value shows in every state. Never hide the timestamp, and never stamp an imported value with the import time.

## Components [#components]

* [RelativeTime](../components/relative-time.mdx) writes the age. The product supplies `staleAfterHours`, which has no default, and `event` separates measured from synced.
* [MetricTile](../components/metric-tile.mdx) mutes past `staleAfterHours` and adds "may be out of date".
* [StatusPill](../components/status-pill.mdx) is removed once the value is stale, never greyed.
* [AlertBanner](../components/alert-banner.mdx) carries a screen-wide condition, such as a queued write that failed to send.

## Content [#content]

* Name what is uncertain: "Last synced 4 hours ago. Your monitor may have taken readings since then. We can't show a current status until it reconnects." Not "Some data may be out of date."
* Tell the reader their entry is safe: "Saved on your phone. It will sync when you're back online."

## Accessibility [#accessibility]

* Entering the stale state is one polite status message per transition, not one per tile (WCAG 2.2 SC 4.1.3).
* The offline notice is announced, never modal, and never takes focus.
* Never grey a value out to show staleness, because it fails the contrast floor. Use words and position.
* Retry is a focusable, labelled control, even where pull-to-refresh exists.
