Data display

Timeline

<forma-timeline>

Chronological or ordered activity with timestamps, state changes, provenance, and single-column mobile flow.

Authoring tag
<forma-timeline>
Category
Data display
Behavior owner
Application content
Canonical source
patterns/timeline.html

Purpose

A timeline is an ordered list of events. Each li has a decorative marker on a vertical rail and a bordered content block holding a meta line (a time element and optional status), a heading, a description and an optional source. Forma draws the rail, markers and spacing; the application decides the order (newest or oldest first), the grouping and what each event says. The list order is the chronology, so it reads the same with or without the rail.

Use when

  • Users need the history of a record: who did what, when, and what state resulted.
  • Events carry a timestamp, a short title and optional status or source attribution.
  • An audit or activity trail must stay readable on a phone as a single column.

Avoid when

  • Events are short notifications in a stream that users triage and act on: use Feed item.
  • The steps are a sequence the user is working through: use Steps or Wizard.
  • The list is a derivation of one displayed value: use Provenance trail.
  • Many uniform events need sorting and filtering: use Data grid or Dense ledger.

Behavior to know

  • Two-column item grid: a 1.25rem marker column and a flexible content column.
  • A 1px rail connects markers; the last item has no rail below it.
  • The meta line wraps and spreads the time and status apart with justify-content: space-between.
  • Markers are hollow circles for every event; state is written in the meta line, not encoded in the marker.

Basic example

The smallest correct markup: the canonical pattern from patterns/timeline.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal timeline

Rendered from the canonical pattern file.

  1. Confirmed

    Invoice issued

    Invoice INV-1042 was issued after review.

    Source: billing workflow
  2. Draft

    Draft updated

    Payment terms and line descriptions changed.

HTML · Minimal timeline Raw HTML for HTML · Minimal timeline
<forma-timeline class="forma-component-tag">
<ol class="forma-timeline" aria-label="Activity history">
  <li class="forma-timeline__item">
    <div class="forma-timeline__marker" aria-hidden="true"></div>
    <div class="forma-timeline__content">
      <div class="forma-timeline__meta"><time datetime="2026-09-22T14:10:00Z">Sep 22 · 14:10</time><span class="forma-status-lozenge" data-state="ok">Confirmed</span></div>
      <h3>Invoice issued</h3>
      <p>Invoice INV-1042 was issued after review.</p>
      <small>Source: billing workflow</small>
    </div>
  </li>
  <li class="forma-timeline__item">
    <div class="forma-timeline__marker" aria-hidden="true"></div>
    <div class="forma-timeline__content">
      <div class="forma-timeline__meta"><time datetime="2026-09-21T19:32:00Z">Sep 21 · 19:32</time><span class="forma-status-lozenge">Draft</span></div>
      <h3>Draft updated</h3>
      <p>Payment terms and line descriptions changed.</p>
    </div>
  </li>
</ol>
</forma-timeline>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

History with an unknown outcome

A payment's history, newest first. The latest event's outcome is not yet known, and the timeline says so with an Unknown status instead of implying failure or success.

  1. Outcome unknown

    Settlement requested

    The bank accepted the request but has not confirmed settlement.

    Source: bank connector
  2. Approved

    Payment approved

    Approved by J. Lindqvist under the finance approval policy.

    Source: approvals
  3. Created

    Payment created

    Created from invoice INV-1042.

HTML · History with an unknown outcome Raw HTML for HTML · History with an unknown outcome
<forma-timeline class="forma-component-tag">
  <ol class="forma-timeline" aria-label="Payment PAY-88122 history">
    <li class="forma-timeline__item">
      <div class="forma-timeline__marker" aria-hidden="true"></div>
      <div class="forma-timeline__content">
        <div class="forma-timeline__meta"><time datetime="2026-09-29T08:20:00Z">Sep 29 · 08:20</time><span class="forma-status-lozenge" data-state="unknown">Outcome unknown</span></div>
        <h3>Settlement requested</h3>
        <p>The bank accepted the request but has not confirmed settlement.</p>
        <small>Source: bank connector</small>
      </div>
    </li>
    <li class="forma-timeline__item">
      <div class="forma-timeline__marker" aria-hidden="true"></div>
      <div class="forma-timeline__content">
        <div class="forma-timeline__meta"><time datetime="2026-09-29T08:02:00Z">Sep 29 · 08:02</time><span class="forma-status-lozenge" data-state="ok">Approved</span></div>
        <h3>Payment approved</h3>
        <p>Approved by J. Lindqvist under the finance approval policy.</p>
        <small>Source: approvals</small>
      </div>
    </li>
    <li class="forma-timeline__item">
      <div class="forma-timeline__marker" aria-hidden="true"></div>
      <div class="forma-timeline__content">
        <div class="forma-timeline__meta"><time datetime="2026-09-28T16:45:00Z">Sep 28 · 16:45</time><span class="forma-status-lozenge">Created</span></div>
        <h3>Payment created</h3>
        <p>Created from invoice INV-1042.</p>
      </div>
    </li>
  </ol>
</forma-timeline>

Click or tap the code once to select all of it, then copy.

Scenario

Event with expandable detail

A configuration change whose full diff is optional reading. The detail sits in a native Disclosure inside the event's content, so the timeline stays scannable and the browser owns open and closed state.

Live demo. 1 native action works here and is verified by an outcome test.

  1. by m.okafor

    Retention policy changed

    Evidence retention changed from 30 days to unlimited.

    Show changed fields

    Retention: 30 days → Unlimited. Export: Manual → Automated after approval.

  2. by system

    Workspace created

HTML · Event with expandable detail Raw HTML for HTML · Event with expandable detail
<forma-timeline class="forma-component-tag">
  <ol class="forma-timeline" aria-label="Workspace settings history">
    <li class="forma-timeline__item">
      <div class="forma-timeline__marker" aria-hidden="true"></div>
      <div class="forma-timeline__content">
        <div class="forma-timeline__meta"><time datetime="2026-09-27T11:05:00Z">Sep 27 · 11:05</time><span>by m.okafor</span></div>
        <h3>Retention policy changed</h3>
        <p>Evidence retention changed from 30 days to unlimited.</p>
        <details class="forma-disclosure" data-forma-motion-weight="light">
          <summary>Show changed fields</summary>
          <div class="forma-disclosure__content">
            <p>Retention: 30 days → Unlimited. Export: Manual → Automated after approval.</p>
          </div>
        </details>
      </div>
    </li>
    <li class="forma-timeline__item">
      <div class="forma-timeline__marker" aria-hidden="true"></div>
      <div class="forma-timeline__content">
        <div class="forma-timeline__meta"><time datetime="2026-09-20T09:30:00Z">Sep 20 · 09:30</time><span>by system</span></div>
        <h3>Workspace created</h3>
      </div>
    </li>
  </ol>
</forma-timeline>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile activity history

The same structure at phone width. The marker column stays fixed at 1.25rem and the content column takes the rest.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • The timeline is already single-column: a fixed 1.25rem marker column beside a minmax(0, 1fr) content column, so it needs no breakpoint.
  • The meta line wraps: at 320px a long status moves below the timestamp instead of overflowing.
  • Headings and descriptions wrap inside the bordered content block; long identifiers should use Identifier & critical value so they break safely.
  • The timeline has no interactive parts of its own; links or disclosures inside events keep their own touch targets.
HTML · Mobile activity history Raw HTML for HTML · Mobile activity history
<forma-timeline class="forma-component-tag">
  <ol class="forma-timeline" aria-label="Ticket SUP-3120 activity">
    <li class="forma-timeline__item">
      <div class="forma-timeline__marker" aria-hidden="true"></div>
      <div class="forma-timeline__content">
        <div class="forma-timeline__meta"><time datetime="2026-09-29T09:12:00Z">09:12</time><span class="forma-status-lozenge" data-state="attention">Awaiting customer reply</span></div>
        <h3>Support replied</h3>
        <p>Asked for the export settings used when the CSV failed.</p>
      </div>
    </li>
    <li class="forma-timeline__item">
      <div class="forma-timeline__marker" aria-hidden="true"></div>
      <div class="forma-timeline__content">
        <div class="forma-timeline__meta"><time datetime="2026-09-29T07:55:00Z">07:55</time><span class="forma-status-lozenge">New</span></div>
        <h3>Ticket opened</h3>
        <p>Cannot export the quarterly usage report as CSV.</p>
      </div>
    </li>
  </ol>
</forma-timeline>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelol.forma-timelinestring—Names the history, for example "Payment PAY-88122 history".
aria-hidden.forma-timeline__markertrue—The marker is decorative; hide it from assistive technology.
datetimetimeISO date-time—Machine-readable event time; the visible text can be relative or abbreviated.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-timelineBlock class—The ordered list; list styling removed.
.forma-timeline__contentElement class—Bordered block holding the meta line, heading, description and source.
.forma-timeline__itemElement class—One event: a marker column and a content column, with the connecting rail drawn from ::before on every item except the last.
.forma-timeline__markerElement class—Decorative hollow circle aligned with the event's first line.
.forma-timeline__metaElement class—Wrapping flex row for the timestamp and status, in small monospace type.
Keyboard interaction
KeysResult
TabReaches links, buttons or disclosure summaries inside events. The timeline itself is not focusable.

Form behavior

Not a form control.

States

Timeline states
StateHow it is expressedPresentation
Eventli.forma-timeline__itemMarker, rail and content block.
Last event:last-childNo rail continues below the marker.
Event statustext or Status lozenge in .forma-timeline__metaStated in words; markers look identical for every status.

Accessibility

Forma provides

  • Uses an ordered list, so assistive technology announces the number of events and each position.
  • Draws the rail with a pseudo-element and asks for the marker to be aria-hidden, so decoration is never announced.
  • Does not encode state in marker color or shape.

Your application supplies

  • Label the list and keep a consistent order; say in the label or a heading whether it is newest or oldest first.
  • Use time datetime for every timestamp and include the time zone where it matters.
  • Give each event a heading at the right level for the page, and write outcome and source as text.
  • If events load incrementally, announce additions with an application live region.

Responsive behavior

  • No breakpoints: the fixed marker column plus flexible content column works from 320px up.
  • The meta line wraps; the content block has min-inline-size: 0, so long text wraps rather than widening the list.
  • Grouping by day or period is application markup, for example a heading before each list.

Motion

  • No animation: markers, rail and content are static. Newly inserted events appear without transition.

Usage guidance

Do

  • Write events as outcomes ("Payment approved") with the actor and source.
  • Show unknown or pending outcomes explicitly.

Avoid

  • Coloring markers to mean success or failure.
  • Mixing ascending and descending order in one view.
  • Putting primary actions inside historical events; actions belong to the current record.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.