Skip to content
opsinjs
Edit this page

Components

TimelineEntry

One dated event in a vertical history, with a neutral rail and marker, the time written as people say it, and any clinical status shown as a nested pill.

Usage

pnpm dlx shadcn@latest add @opsinjs/timeline-entry

The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.

import { TimelineEntry } from "@/components/ui/timeline-entry"
<ol>
  <TimelineEntry
    when="2026-03-14T08:12:00+00:00"
    now={new Date().toISOString()}
    title="Repeat prescription issued"
    status="watch"
    isLast
  >
    Issued by the example clinic.
  </TimelineEntry>
</ol>

Examples

Theme
Density
Text
Status
Accent theme
Accent
timeline-entry · base base · style base-lyraOpen under the product theme

A history on one rail

Every row names and dates its event, the connector runs to the last entry and stops, and one row carries a status the product assigned.

Theme
Density
Text
Status
Accent theme
Accent
timeline-entry-in-a-history · base base · style base-lyraOpen under the product theme
timeline-entry-in-a-history.tsx
import { TimelineEntry } from "@/components/ui/timeline-entry"

const NOW = "2026-03-14T11:12:00+00:00"

const EVENTS: { when: string; title: string; body: string; status?: "watch" }[] = [
  {
    when: "2026-03-14T09:30:00+00:00",
    title: "Example note added",
    body: "Written by the example app.",
  },
  {
    when: "2026-03-12T18:00:00+00:00",
    title: "Example reminder set",
    body: "Set by the example app.",
    status: "watch",
  },
  {
    when: "2026-03-02T09:00:00+00:00",
    title: "Example entry recorded",
    body: "Recorded by the example app.",
  },
]

export default function TimelineEntryInAHistory() {
  return (
    <ol className="m-0 flex w-full max-w-md list-none flex-col p-0">
      {EVENTS.map((event, index) => (
        <TimelineEntry
          key={event.title}
          when={event.when}
          now={NOW}
          title={event.title}
          status={event.status}
          isLast={index === EVENTS.length - 1}
        >
          {event.body}
        </TimelineEntry>
      ))}
    </ol>
  )
}

The status rides the pill

Two entries alike but for status. The rail, the marker and the entry stay neutral, and status changes only the pill beside the title.

Theme
Density
Text
Status
Accent theme
Accent
timeline-entry-with-a-status · base base · style base-lyraOpen under the product theme
timeline-entry-with-a-status.tsx
import { TimelineEntry } from "@/components/ui/timeline-entry"

const NOW = "2026-03-14T11:12:00+00:00"

export default function TimelineEntryWithAStatus() {
  return (
    <ol className="m-0 flex w-full max-w-md list-none flex-col p-0">
      <TimelineEntry
        when="2026-03-14T08:12:00+00:00"
        now={NOW}
        title="Example result filed"
        status="attention"
      >
        The status rides the pill. The entry, its rail and its marker stay
        neutral.
      </TimelineEntry>
      <TimelineEntry when="2026-03-11T08:12:00+00:00" now={NOW} title="Example result filed" isLast>
        The same entry with no status. Nothing about the rail or the marker
        changes.
      </TimelineEntry>
    </ol>
  )
}

When to use it

Use it when

  • Showing one recorded event in a history the product lays out: a prescription issued, a test booked, a note added.
  • Placing a single dated entry on a vertical rail, where the product owns the list around it.
  • A row that needs the recorded time in words, with an optional status beside the event.

Do not use it when

  • You want one component to own the whole history, its ordering and its data model.Use card instead.
  • You are charting one reading as it moves over time rather than listing distinct events.Use trend-sparkline instead.
  • You only need to say when a single thing happened, with no rail, marker or event around it.Use relative-time instead.
  • You are recording medicine doses taken and missed, which has its own shape.Use dose-tracker instead.
  • You need the reader to write down what happened rather than read a recorded event.Use log-sheet instead.

Clinical meaning

Asserts. That the named event was recorded at the given instant, and nothing more. A gap between two entries is not evidence that nothing happened in it.

Never read as. A diagnosis, a verdict, or a guarantee that the history is complete or current. The entry never triages, diagnoses or advises, and every word in it is the product's.

Colour axis. Neither, on the entry. The rail and the marker are neutral chrome. A supplied status is delegated to a nested StatusPill, which carries the status axis with a word and a glyph. See Two colour axes.

Thresholds. The product owns them all. The entry holds no threshold, no staleness boundary and no event text. Trends and uncertainty covers why it never guesses whether a recorded time is too old to trust, and why one entry is one event, not a direction.

Accessibility

The rail and the marker carry aria-hidden, so a screen reader meets the time, the title, any status word and the body in reading order. The recorded time is the system RelativeTime, a semantic time element, so the exact instant stays in the accessibility tree when only the phrase shows. Nothing in the entry is focusable, so keyboard, focus and target size do not apply. Axe, target-size, focus-visible and 320px reflow checks were clean, and the audit changed nothing.

Residual items.

  • The marker and the connector are decorative chrome under aria-hidden, so they are exempt from Non-text Contrast (1.4.11). They use role tokens anyway.
  • The root renders a bare li, so the product must supply the ol or ul around it for list semantics to hold.
  • On Safari with VoiceOver a list-style: none list can drop its list role, a platform quirk shared by every list based component here rather than a fault in this one.
KeyActionNotes
TabSkips the entryNothing here is focusable, so a long history costs a keyboard user no stops.
Shift+TabSkips the entrySame in reverse. The time, the title and the body are reached by reading.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor

These are the measured token pairs this component draws colour from, not a measurement of the component itself.

Props interface

Prop

Type

Generated from TimelineEntryProps in registry/bases/base/timeline-entry.tsx.

when is ISO 8601 with an offset, the contract RelativeTime enforces on its at. now is required because this component never reads the clock, so read the clock once per screen and pass one value to every entry. The event word is fixed and no locale is forwarded, so a product needing either composes RelativeTime directly.