-
Invoice issued · Extended localized content for verification and layout resilience
Invoice INV-1042 was issued after review.
Source: billing workflow -
Draft updated
Payment terms and line descriptions changed.
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.
Minimal timeline
Rendered from the canonical pattern file.
-
Invoice issued
Invoice INV-1042 was issued after review.
Source: billing workflow -
Draft updated
Payment terms and line descriptions changed.
<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
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.
-
Settlement requested
The bank accepted the request but has not confirmed settlement.
Source: bank connector -
Payment approved
Approved by J. Lindqvist under the finance approval policy.
Source: approvals -
Payment created
Created from invoice INV-1042.
<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.
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.
-
Retention policy changed
Evidence retention changed from 30 days to unlimited.
Show changed fields
Retention: 30 days → Unlimited. Export: Manual → Automated after approval.
-
Workspace created
<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 activity history
The same structure at phone width. The marker column stays fixed at 1.25rem and the content column takes the rest.
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.
<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.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
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.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
aria-label | ol.forma-timeline | string | — | Names the history, for example "Payment PAY-88122 history". |
aria-hidden | .forma-timeline__marker | true | — | The marker is decorative; hide it from assistive technology. |
datetime | time | ISO date-time | — | Machine-readable event time; the visible text can be relative or abbreviated. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-timeline | Block class | — | The ordered list; list styling removed. |
.forma-timeline__content | Element class | — | Bordered block holding the meta line, heading, description and source. |
.forma-timeline__item | Element 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__marker | Element class | — | Decorative hollow circle aligned with the event's first line. |
.forma-timeline__meta | Element class | — | Wrapping flex row for the timestamp and status, in small monospace type. |
| Keys | Result |
|---|---|
| Tab | Reaches links, buttons or disclosure summaries inside events. The timeline itself is not focusable. |
Form behavior
Not a form control.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Event | li.forma-timeline__item | Marker, rail and content block. |
| Last event | :last-child | No rail continues below the marker. |
| Event status | text or Status lozenge in .forma-timeline__meta | Stated 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 datetimefor 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.