Timeline
<Timeline> renders a vertical track of <TimelinePoint> markers that stay in proportion to the range you supply. Each point can show a title, summary, extended description, highlight state, and related IIIF resources. Prefer proportional spacing for historical accuracy, or set scale="uniform" when you want evenly distributed beats regardless of their timestamps. Likewise, use align to position the spine itself—keep it centered (default) or move it flush against the left/right edge so the cards fill the remaining width (per-point side is ignored when you do so).
Ranges accept year-, month-, or day-level precision (1701, July 1776, or 1776-07-04). When you provide a range the points are spaced mathematically, so clusters of events appear closer together in the scroll container. Control the viewport with the height prop—pass a pixel value, rem value, or percentage, and the component honors it.
Example: Empire arc
Below is a scrolling demo that covers 1750–1900. range keeps each point proportional, threshold={5} collapses events within five years of one another, and steps={50} draws guide ticks every fifty years.
Empire and Control in Colonial India
Famine, mapping, policy, and revolt across one and a half centuries.
1750 – 1900
Keyed legend
Pair the new timelineKey prop with matching key values on each <TimelinePoint> to color-code entries and print a legend beneath the track. Colors auto-rotate from your accent palette, so you can focus on labeling the categories.
A commission lifecycle
Follow the work from patron letter to gallery opening.
1880 – 1892
- Commission
- Research
- Studio
API
Timeline
| Prop | Type | Required | Notes |
|---|---|---|---|
title | string | Optional heading rendered above the track. | |
description | string | Short blurb shown under the heading. | |
range | object | {start, end, granularity} controls proportional spacing. Granularity accepts year, month, or day. | |
scale | 'time' · 'uniform' | 'time' (default) honors timestamps; 'uniform' spaces points evenly along the track. | |
align | 'center' · 'left' · 'right' | Centers the spine (default) or pushes it flush left/right so cards occupy the remaining width (overrides each point's side). | |
threshold | number | Collapse points that fall within this many units of the selected granularity. | |
steps | number | Draw evenly spaced tick marks along the spine. | |
height | string or number | Scrolling viewport height. Numbers are treated as pixels. | |
locale | string | Locale tag used for formatted dates. | |
timelineKey | Array<{ id, label }> | Optional legend configuration. Accepts {id, label} entries (also via keyConfig or legend) and colors matching points. | |
children | nodes | ✅ | One or more <TimelinePoint> elements. |
TimelinePoint
| Prop | Type | Required | Notes |
|---|---|---|---|
date / value | string | ✅ | Accepts ISO dates (1776-07-04), months (July 1776), or bare years. |
title | string | ✅ | Label shown beside the point. |
summary | string | Short sentence under the title. | |
description | string | Long-form copy shown inside the detail panel. | |
side | 'left' · 'right' | Pin the marker to a side; otherwise it alternates. | |
highlight | boolean | Draw the point with the accent color. | |
key / timelineKey | string | Match a timelineKey entry on <Timeline> to color the connector + legend dot. | |
referencedManifests | array | List of manifest IDs to resolve into teaser cards. | |
iiifResources | array | Provide {href, label} entries for non-manifest resources. | |
children | nodes | Additional markup rendered in the detail drawer. |
Examples
Range spacing
Give the component a range so events sit in proportion to each other. Combine threshold and steps to cluster near-duplicate years and draw guide ticks.
Empire and Control in Colonial India
Moments of famine, conflict, and policy between 1750 and 1900.
1750 – 1900
Uniform spacing
When the narrative needs consistent pacing over historical precision, set scale="uniform". This ignores timestamps for layout purposes so each point receives equal vertical spacing while still showing its actual date labels.
Restoration Phases
Major conservation checkpoints rendered with even spacing.
1816 – 2021
Single-sided layout
Anchor every entry to one side by moving the spine itself with the align prop. When you set align="left", the vertical line sits flush left and every card renders to its right; align="right" mirrors that layout. Individual <TimelinePoint side="…" /> values are ignored in these modes.
Curatorial milestones
Museum-side checkpoints with the spine flush left.
1932 – 2022
If you need the cards to live on the opposite side—perhaps to align with adjacent prose or an illustration—flip the prop to align="right" so the spine slides to the right edge and cards fill the left.
Field research
Documentation checkpoints mirrored to the right.
1964 – 2023
Referenced manifests
Directly referenced works in your timeline be adding referencedManifests to a point. This automatically resolves links to a relative local in /works/ if available.
Rich details
Use children to add inline prose and cite additional IIIF resources beyond the main manifest list.
Pinned sides
Pass side="left" or side="right" when a point should stay on one side of the spine instead of alternating. Note this is ignored when the parent <Timeline> has align="left" or align="right" since those modes pin all points to one side by default.
1781 – 1790
Clustered groups
Use threshold to group events that fall within a set number of years for the current granularity.
1800 – 1820