Appearance
Timeline
Timeline provides composable primitives for building time-based layouts such as Gantt charts, schedules, and project timelines. It is a compound component with five sub-components: Root, Viewport, Row, Interval, and Link.
Import
tsx
import { Timeline } from "@tailor-platform/app-shell";The additional examples also import Text from @tailor-platform/app-shell.
Basic Usage
tsx
function BasicUsage() {
return (
<Timeline.Root
start={0}
end={100}
className="overflow-hidden rounded-md border border-border bg-background"
>
<Timeline.Viewport
axis={{
className: "border-b border-border bg-muted",
guides: [0, 50, 100].map((at) => ({
at,
axisClassName: "bg-border",
bodyClassName: "bg-border",
})),
levels: [
{
kind: "spans",
items: [
{ start: 0, end: 50, label: "Phase 1" },
{ start: 50, end: 100, label: "Phase 2" },
],
},
],
}}
>
<Timeline.Row height={40} background={{ className: "bg-blue-500/5" }}>
<Timeline.Interval start={10} end={35} insetY={4}>
<div className="flex h-full items-center justify-center rounded-md bg-blue-600 text-label-md text-white">
Planning
</div>
</Timeline.Interval>
</Timeline.Row>
</Timeline.Viewport>
</Timeline.Root>
);
}Sub-components
| Sub-component | Description |
|---|---|
Timeline.Root | Provides the shared time range for all nested timeline primitives |
Timeline.Viewport | Renders the axis, decorations, scrolling area, and link overlay layer |
Timeline.Row | Defines one horizontal lane with a fixed height and optional background |
Timeline.Interval | Positions content across a time range inside a row |
Timeline.Link | Draws an orthogonal dependency connector between two named Interval elements |
TimeValue
All time position props (start, end, at) accept either a Date object or a millisecond-precision number timestamp.
tsx
// Using Date objects
<Timeline.Root start={new Date("2024-01-01")} end={new Date("2024-12-31")}>
// Using numeric timestamps
<Timeline.Root start={0} end={100}>Props
Timeline.Root Props
| Prop | Type | Default | Description |
|---|---|---|---|
start | Date | number | — | Inclusive start of the overall timeline range |
end | Date | number | — | Inclusive end of the overall timeline range |
children | React.ReactNode | — | Timeline subtree, usually a Timeline.Viewport |
className | string | — | Additional CSS classes applied to the root element |
style | CSSProperties | — | Inline style applied to the root element |
Timeline.Viewport Props
| Prop | Type | Default | Description |
|---|---|---|---|
children | React.ReactNode | — | Rows and links, in any order |
axis | TimelineAxis | — | Axis configuration: guides and stacked header levels |
decorations | TimelineDecorations | — | Decorative layers: bands and markers |
linkDefaults | TimelineLinkDefaults | — | Shared defaults applied to all Timeline.Link nodes in this viewport |
canvasWidth | number | — | Fixed canvas width in pixels for horizontally scrollable timelines |
stickyAxis | boolean | false | Pins the axis to the top of the viewport during vertical scrolling |
className | string | — | Additional CSS classes applied to the scroll viewport |
style | CSSProperties | — | Inline style applied to the scroll viewport |
Timeline.Row Props
| Prop | Type | Default | Description |
|---|---|---|---|
children | React.ReactNode | — | Row contents, typically Timeline.Interval elements |
height | number | 32 | Row height in pixels |
background | TimelineRowBackground | null | — | Optional background rendered in a dedicated layer, in front of bands but behind guide lines |
className | string | — | Additional CSS classes applied to the row content container |
style | CSSProperties | — | Inline style applied to the row content container |
Timeline.Interval Props
| Prop | Type | Default | Description |
|---|---|---|---|
start | Date | number | — | Start of the interval |
end | Date | number | — | End of the interval |
children | React.ReactNode | — | Rendered content for the interval |
id | string | — | Stable id used by Timeline.Link to reference this interval |
insetY | number | 0 | Top and bottom inset in pixels within the row |
className | string | — | Additional CSS classes applied to the positioned interval container |
style | CSSProperties | — | Inline style applied to the positioned interval container |
Timeline.Link Props
| Prop | Type | Default | Description |
|---|---|---|---|
from | string | — | Source Timeline.Interval id |
to | string | — | Target Timeline.Interval id |
fromAnchor | "start" | "center" | "end" | "end" | Source anchor used for routing |
toAnchor | "start" | "center" | "end" | "start" | Target anchor used for routing |
arrow | boolean | — | Overrides the viewport-level linkDefaults.arrow |
gap | number | — | Overrides the viewport-level linkDefaults.gap |
strokeWidth | number | — | Optional stroke width for the link path |
className | string | — | Additional CSS classes applied to the link SVG |
style | CSSProperties | — | Inline style applied to the link SVG |
Type Reference
TimelineAxis
Axis configuration for Timeline.Viewport.
| Field | Type | Description |
|---|---|---|
guides | TimelineGuide[] | Vertical boundary lines rendered in the axis and body |
levels | TimelineAxisLevel[] | Stacked header levels rendered above the body |
className | string | Optional class applied to the axis container |
TimelineAxisLevel
A stacked axis level. Has a discriminated union kind field:
kind: "spans"— renders labeled time ranges (TimelineAxisSpan[])kind: "ticks"— renders labeled point-in-time markers (TimelineAxisTick[])
| Field | Type | Default | Description |
|---|---|---|---|
kind | "spans" | "ticks" | — | Level rendering mode |
items | TimelineAxisSpan[] | TimelineAxisTick[] | — | Items to render in this level |
height | number | 28 | Height of this axis level in pixels |
className | string | — | Optional class applied to the level container |
TimelineGuide
A vertical guide line rendered in both the axis and the body.
| Field | Type | Description |
|---|---|---|
at | Date | number | Time position for the guide line |
key | React.Key | Optional stable React key |
axisClassName | string | Optional class for the axis portion of the guide |
axisStyle | CSSProperties | Optional style for the axis portion of the guide |
bodyClassName | string | Optional class for the body portion of the guide |
bodyStyle | CSSProperties | Optional style for the body portion of the guide |
TimelineDecorations
Decorative layers rendered by Timeline.Viewport.
| Field | Type | Description |
|---|---|---|
bands | TimelineBand[] | Background range highlights rendered behind rows |
markers | TimelineMarker[] | Vertical markers rendered in the axis and/or body |
TimelineBand
A decorative horizontal band rendered behind rows.
| Field | Type | Description |
|---|---|---|
start | Date | number | Start of the band |
end | Date | number | End of the band |
key | React.Key | Optional stable React key |
color | string | Optional background color convenience prop |
className | string | Optional class applied to the band element |
style | CSSProperties | Optional inline style applied to the band |
TimelineMarker
A decorative vertical marker line.
| Field | Type | Default | Description |
|---|---|---|---|
at | Date | number | — | Time position for the marker |
key | React.Key | — | Optional stable React key |
color | string | — | Optional line color convenience prop |
label | React.ReactNode | — | Optional marker label |
placement | "axis" | "body" | "both" | "body" | Controls where the marker is rendered |
className | string | — | Optional class applied to the outer marker wrapper |
lineClassName | string | — | Optional class applied to the marker line |
labelClassName | string | — | Optional class applied to the marker label |
TimelineLinkDefaults
Shared defaults for all Timeline.Link nodes inside one viewport.
| Field | Type | Default | Description |
|---|---|---|---|
routing | "orthogonal" | "orthogonal" | Link routing strategy |
arrow | boolean | true | Whether links end with an arrow marker |
gap | number | 16 | Horizontal gap in px used when routing out of/into items |
strokeWidth | number | — | Optional default stroke width for link paths |
className | string | — | Optional class applied to each link SVG |
style | CSSProperties | — | Optional style applied to each link SVG |
TimelineRowBackground
Background content for a row rendered in a dedicated layer (in front of bands, behind guides).
| Field | Type | Description |
|---|---|---|
className | string | Optional class applied to the background layer element |
style | CSSProperties | Optional style applied to the background layer element |
Examples
Horizontal Scrolling
Use canvasWidth on Timeline.Viewport to enable horizontal scrolling. The example constrains the visible width, so scroll right to reveal the Release task:
tsx
function HorizontalScrolling() {
const tasks = [
{ name: "Planning", start: 5, end: 25, color: "bg-blue-600" },
{ name: "Implementation", start: 30, end: 70, color: "bg-emerald-700" },
{ name: "Release", start: 80, end: 98, color: "bg-violet-600" },
];
return (
<div className="space-y-3">
<Text.p>Scroll horizontally to see Release at the far end of the fixed-width canvas.</Text.p>
<Timeline.Root
start={0}
end={100}
className="max-w-xl overflow-hidden rounded-md border border-border bg-background"
>
<Timeline.Viewport
canvasWidth={1400}
axis={{
className: "border-b border-border bg-muted",
guides: [25, 50, 75].map((at) => ({
at,
axisClassName: "bg-border",
bodyClassName: "bg-border",
})),
levels: [
{
kind: "spans",
items: [
{ start: 0, end: 25, label: "Week 1" },
{ start: 25, end: 50, label: "Week 2" },
{ start: 50, end: 75, label: "Week 3" },
{ start: 75, end: 100, label: "Week 4" },
],
},
],
}}
>
{tasks.map((task, index) => (
<Timeline.Row
key={task.name}
height={44}
className="border-b border-border last:border-b-0"
background={index % 2 === 1 ? { className: "bg-blue-500/10" } : undefined}
>
<Timeline.Interval start={task.start} end={task.end} insetY={6}>
<div className={`flex h-full items-center rounded px-3 text-white ${task.color}`}>
{task.name}
</div>
</Timeline.Interval>
</Timeline.Row>
))}
</Timeline.Viewport>
</Timeline.Root>
</div>
);
}Sticky Axis
Pin the axis to the top during vertical scrolling with stickyAxis. Give the viewport a bounded height and enable vertical scrolling; this example contains more task rows than fit in its 220px viewport. Scroll inside it to keep the sprint labels in view:
tsx
function StickyAxis() {
const colors = ["bg-blue-600", "bg-emerald-700", "bg-amber-700", "bg-violet-600", "bg-rose-600"];
const tasks = Array.from({ length: 10 }, (_, index) => ({
name: `Task ${index + 1}`,
start: 5 + index * 3,
end: 45 + index * 4,
color: colors[index % colors.length],
}));
return (
<div className="space-y-3">
<Text.p>
Scroll inside the timeline. The sprint labels stay at the top while the task rows move.
</Text.p>
<Timeline.Root
start={0}
end={100}
className="overflow-hidden rounded-md border border-border bg-background"
>
<Timeline.Viewport
stickyAxis
style={{ height: 220, overflowY: "auto" }}
axis={{
className: "border-b border-border bg-muted",
guides: [{ at: 50, axisClassName: "bg-border", bodyClassName: "bg-border" }],
levels: [
{
kind: "spans",
items: [
{ start: 0, end: 50, label: "Sprint 1" },
{ start: 50, end: 100, label: "Sprint 2" },
],
},
],
}}
>
{tasks.map((task, index) => (
<Timeline.Row
key={task.name}
height={42}
className="border-b border-border last:border-b-0"
background={index % 2 === 1 ? { className: "bg-blue-500/10" } : undefined}
>
<Timeline.Interval start={task.start} end={task.end} insetY={5}>
<div className={`flex h-full items-center rounded px-3 text-white ${task.color}`}>
{task.name}
</div>
</Timeline.Interval>
</Timeline.Row>
))}
</Timeline.Viewport>
</Timeline.Root>
</div>
);
}Dependency Links
Use id on Timeline.Interval and Timeline.Link to draw dependency connectors:
tsx
function DependencyLinks() {
return (
<Timeline.Root
start={0}
end={100}
className="overflow-hidden rounded-md border border-border bg-background"
>
<Timeline.Viewport
axis={{
guides: [25, 50, 75].map((at) => ({ at, bodyClassName: "bg-border" })),
}}
linkDefaults={{ style: { color: "var(--muted-foreground)" }, strokeWidth: 1.5 }}
>
<Timeline.Row height={40} className="border-b border-border">
<Timeline.Interval id="task-a" start={10} end={40} insetY={4}>
<div className="flex h-full items-center justify-center rounded-md bg-blue-600 text-label-md text-white">
Task A
</div>
</Timeline.Interval>
</Timeline.Row>
<Timeline.Row height={40} background={{ className: "bg-blue-500/10" }}>
<Timeline.Interval id="task-b" start={50} end={80} insetY={4}>
<div className="flex h-full items-center justify-center rounded-md bg-emerald-700 text-label-md text-white">
Task B
</div>
</Timeline.Interval>
</Timeline.Row>
<Timeline.Link from="task-a" to="task-b" />
</Timeline.Viewport>
</Timeline.Root>
);
}Background Bands and Markers
Use decorations to add background highlights and vertical marker lines. The release-freeze interval is named in the axis as well as shaded, and the Today marker is labelled in both the axis and body, so the meaning is not conveyed by colour alone:
tsx
function BackgroundBandsAndMarkers() {
return (
<div className="space-y-3">
<Text.p>The shaded release freeze spans days 60–80. Today is marked at day 45.</Text.p>
<Timeline.Root
start={0}
end={100}
className="overflow-hidden rounded-md border border-border bg-background"
>
<Timeline.Viewport
axis={{
className: "border-b border-border bg-muted",
guides: [20, 40, 60, 80].map((at) => ({
at,
axisClassName: "bg-border",
bodyClassName: "bg-border",
})),
levels: [
{
kind: "spans",
items: [
{ start: 0, end: 60, label: "Development" },
{ start: 60, end: 80, label: "Release freeze" },
{ start: 80, end: 100, label: "Release" },
],
},
],
}}
decorations={{
bands: [{ start: 60, end: 80, className: "bg-amber-500/15" }],
markers: [{ at: 45, color: "#e11d48", label: "Today", placement: "both" }],
}}
>
<Timeline.Row height={52} className="border-b border-border">
<Timeline.Interval start={10} end={55} insetY={12}>
<div className="flex h-full items-center rounded bg-emerald-700 px-3 text-white">
Build
</div>
</Timeline.Interval>
</Timeline.Row>
<Timeline.Row height={52} background={{ className: "bg-blue-500/5" }}>
<Timeline.Interval start={65} end={95} insetY={12}>
<div className="flex h-full items-center rounded bg-violet-600 px-3 text-white">
Verify and release
</div>
</Timeline.Interval>
</Timeline.Row>
</Timeline.Viewport>
</Timeline.Root>
</div>
);
}Row Background
Use background on Timeline.Row to apply a background that respects guide lines:
tsx
function RowBackground() {
return (
<Timeline.Root
start={0}
end={100}
className="overflow-hidden rounded-md border border-border bg-background"
>
<Timeline.Viewport axis={{ guides: [{ at: 50, bodyClassName: "bg-border" }] }}>
<Timeline.Row height={40} background={{ className: "bg-blue-500/10" }}>
<Timeline.Interval start={10} end={35} insetY={4}>
<div className="flex h-full items-center justify-center rounded-md bg-blue-600 text-label-md text-white">
Planning
</div>
</Timeline.Interval>
</Timeline.Row>
</Timeline.Viewport>
</Timeline.Root>
);
}