Timeline
Records as bars between two dates, in sections, a sticky column of names. Drag or Alt+arrows to move.
import { Timeline } from "@forgeron/ui";Safety audit
import { Timeline } from "@forgeron/ui";
const projects = [
{
id: "lyon",
name: "Lyon depot",
color: "var(--accent)",
start: "2026-10-12",
end: "2027-01-15",
milestones: [
{ id: "lease", label: "Lease signed", date: "2026-10-15", done: true },
{ id: "racks", label: "Dock and racks", date: "2026-12-05" },
],
},
{
id: "q4",
name: "Q4 closing",
color: "var(--success)",
start: "2026-11-02",
end: "2026-12-31",
milestones: [{ id: "pack", label: "Auditor pack", date: "2026-12-15" }],
},
{
id: "rates",
name: "Carrier rates",
color: "var(--warning)",
start: "2026-11-16",
end: "2026-12-04",
},
{ id: "audit", name: "Safety audit", end: "2026-12-10" },
];
export default function Projects() {
return (
<div style={{ width: "100%", height: 230, display: "flex", border: "1px solid var(--line)" }}>
<Timeline records={projects} today="2026-11-18" toolbar={false} labelWidth={120} />
</div>
);
}Alt and the arrows move the dates, by a day; add Shift to move the end alone.
Fire exit signage audit
Quarterly safety walk
// Issues from useListView, grouped by status, as they would sit in a list view. Drag a bar, its
// edges, or press Alt and the arrows on a row to change its dates.
import {
STATUS_NAMES,
StatusGlyph,
Timeline,
useListView,
type IssueItem,
type StatusKind,
type ViewSpec,
} from "@forgeron/ui";
import { useState } from "react";
type Planned = IssueItem & { start?: string };
const STATUSES: StatusKind[] = ["progress", "todo", "backlog"];
const COLORS: Partial<Record<StatusKind, string>> = {
progress: "var(--accent)",
todo: "var(--ink-muted)",
};
const initial: Planned[] = [
{
id: "OPS-40",
title: "Supplier invoices arrive twice",
status: "progress",
start: "2026-11-10",
due: "2026-11-20",
},
{
id: "OPS-37",
title: "Carrier rates: import the new grid",
status: "progress",
start: "2026-11-16",
due: "2026-11-27",
},
{
id: "OPS-41",
title: "Dock schedule for Lyon",
status: "todo",
start: "2026-11-23",
due: "2026-12-04",
},
{ id: "OPS-38", title: "Fire exit signage audit", status: "todo", due: "2026-11-19" },
{ id: "OPS-35", title: "Quarterly safety walk", status: "backlog", due: "2026-12-02" },
];
const spec: ViewSpec<Planned> = {
read: (issue, field) => (field === "status" ? issue.status : null),
groupings: {
status: { key: (i) => i.status, order: STATUSES, name: (k) => STATUS_NAMES[k as StatusKind] },
},
};
export default function EditableIssues() {
const [issues, setIssues] = useState(initial);
const [last, setLast] = useState("Drag a bar, or Alt and the arrows on a row");
const view = useListView(issues, spec, {
defaultDisplay: {
layout: "timeline",
grouping: "status",
ordering: "",
toggles: {},
properties: [],
},
});
return (
<div style={{ width: "100%", display: "grid", gap: 12 }}>
<div style={{ height: 340, display: "flex", border: "1px solid var(--line)" }}>
<Timeline
groups={view.groups.map((g) => ({
...g,
glyph: <StatusGlyph status={g.key as StatusKind} />,
}))}
getColor={(i) => COLORS[i.status]}
today="2026-11-18"
defaultZoom="weeks"
onOpen={(id) => setLast(`Open ${id}`)}
onChange={(id, { start, end }) => {
setIssues((all) =>
all.map((i) =>
i.id === id ? { ...i, start: start ?? undefined, due: end ?? undefined } : i,
),
);
setLast(`${id}: ${start ?? "no start"} → ${end ?? "no end"}`);
}}
/>
</div>
<span style={{ font: "400 11px/1 var(--font-mono)", color: "var(--ink-dim)" }}>{last}</span>
</div>
);
}ISO 9001 audit
// A roadmap by quarters, with the zoom and Today held outside the block (a display menu, a
// toolbar of your own) through `zoom` and the `scrollToToday` handle.
import { Button, Segmented, Timeline, type TimelineHandle, type TimelineZoom } from "@forgeron/ui";
import { useRef, useState } from "react";
const initiatives = [
{
id: "eu",
name: "Second warehouse",
color: "var(--accent)",
start: "2026-07-01",
end: "2027-03-31",
},
{
id: "books",
name: "Books in Odoo",
color: "var(--success)",
start: "2026-09-14",
end: "2026-12-31",
},
{
id: "fleet",
name: "Electric fleet",
color: "var(--warning)",
start: "2027-01-04",
end: "2027-06-30",
},
{ id: "iso", name: "ISO 9001 audit", end: "2027-02-15" },
];
export default function Roadmap() {
const [zoom, setZoom] = useState<TimelineZoom>("quarters");
const timeline = useRef<TimelineHandle>(null);
return (
<div style={{ width: "100%", display: "grid", gap: 8 }}>
<div style={{ display: "flex", gap: 8, justifyContent: "flex-end" }}>
<Button size="sm" onClick={() => timeline.current?.scrollToToday()}>
Today
</Button>
<Segmented
label="Zoom"
value={zoom}
onChange={(z) => setZoom(z as TimelineZoom)}
options={[
{ value: "months", label: "Months" },
{ value: "quarters", label: "Quarters" },
]}
/>
</div>
<div style={{ height: 220, display: "flex", border: "1px solid var(--line)" }}>
<Timeline
ref={timeline}
records={initiatives}
zoom={zoom}
onZoomChange={setZoom}
weekNumbers
today="2026-11-18"
toolbar={false}
/>
</div>
</div>
);
}API → Props
| Prop | Type | Default | Description |
|---|---|---|---|
groups | { key, name, glyph?, records }[] | — | The rows in sections: useListView's groups as they are. |
records | T[] | — | The rows without sections, when there are no groups. |
getId | (record) => string | record.id | The key of a record. |
getLabel | (record) => string | title, else name | Its name, also said to assistive technology. |
getStart | (record) => string | null | record.start | The first day, YYYY-MM-DD. |
getEnd | (record) => string | null | end, else due, else target | The last day. With no start, the record is a point: a due date. |
getColor | (record) => string | undefined | record.color | A CSS colour for its mark, e.g. var(--accent). Grey without one. |
getMilestones | (record) => { id, label, date, done? }[] | record.milestones | Diamonds on the row; filled in ember once reached. |
renderLabel / renderBar | (record) => ReactNode | — | The name cell and the inside of a bar. An issue's id and title by default. |
zoom / defaultZoom | "weeks" | "months" | "quarters" | "months" | A day is 28, 6 or 2 px. Controlled or not. |
onZoomChange | (zoom) => void | — | When the zoom changes. |
today | string | the device's date | YYYY-MM-DD: marked in ember. |
selected / defaultSelected | string | null | — | The current record, marked. Controlled or not. |
onSelectedChange | (id: string) => void | — | When the arrows or a click move the current record. |
onOpen | (id: string) => void | — | A click or Enter on a record. |
onChange | (id, { start, end }) => void | — | Makes dates editable: drag a bar or its edges; Alt+arrows on a row move it (a day by weeks, a week otherwise), Shift for the end alone. |
collapsed / defaultCollapsed | string[] | — | The keys of the folded sections. Controlled or not. |
onCollapsedChange | (keys: string[]) => void | — | When a section is folded or opened. |
toolbar | boolean | true | Today and the zoom or mode above. Off when a display menu holds them. |
weekNumbers | boolean | false | W47 instead of the date of each Monday, by months. |
labelWidth | number | 240 | The width of the name column, in px. |
ref | Ref<{ scrollToToday }> | — | Scrolls today into view, for a Today button of your own. |
className | string | — | Extra classes. |