Skip to content
View as Markdown

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-componentDescription
Timeline.RootProvides the shared time range for all nested timeline primitives
Timeline.ViewportRenders the axis, decorations, scrolling area, and link overlay layer
Timeline.RowDefines one horizontal lane with a fixed height and optional background
Timeline.IntervalPositions content across a time range inside a row
Timeline.LinkDraws 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 ​

PropTypeDefaultDescription
startDate | number—Inclusive start of the overall timeline range
endDate | number—Inclusive end of the overall timeline range
childrenReact.ReactNode—Timeline subtree, usually a Timeline.Viewport
classNamestring—Additional CSS classes applied to the root element
styleCSSProperties—Inline style applied to the root element

Timeline.Viewport Props ​

PropTypeDefaultDescription
childrenReact.ReactNode—Rows and links, in any order
axisTimelineAxis—Axis configuration: guides and stacked header levels
decorationsTimelineDecorations—Decorative layers: bands and markers
linkDefaultsTimelineLinkDefaults—Shared defaults applied to all Timeline.Link nodes in this viewport
canvasWidthnumber—Fixed canvas width in pixels for horizontally scrollable timelines
stickyAxisbooleanfalsePins the axis to the top of the viewport during vertical scrolling
classNamestring—Additional CSS classes applied to the scroll viewport
styleCSSProperties—Inline style applied to the scroll viewport

Timeline.Row Props ​

PropTypeDefaultDescription
childrenReact.ReactNode—Row contents, typically Timeline.Interval elements
heightnumber32Row height in pixels
backgroundTimelineRowBackground | null—Optional background rendered in a dedicated layer, in front of bands but behind guide lines
classNamestring—Additional CSS classes applied to the row content container
styleCSSProperties—Inline style applied to the row content container

Timeline.Interval Props ​

PropTypeDefaultDescription
startDate | number—Start of the interval
endDate | number—End of the interval
childrenReact.ReactNode—Rendered content for the interval
idstring—Stable id used by Timeline.Link to reference this interval
insetYnumber0Top and bottom inset in pixels within the row
classNamestring—Additional CSS classes applied to the positioned interval container
styleCSSProperties—Inline style applied to the positioned interval container
PropTypeDefaultDescription
fromstring—Source Timeline.Interval id
tostring—Target Timeline.Interval id
fromAnchor"start" | "center" | "end""end"Source anchor used for routing
toAnchor"start" | "center" | "end""start"Target anchor used for routing
arrowboolean—Overrides the viewport-level linkDefaults.arrow
gapnumber—Overrides the viewport-level linkDefaults.gap
strokeWidthnumber—Optional stroke width for the link path
classNamestring—Additional CSS classes applied to the link SVG
styleCSSProperties—Inline style applied to the link SVG

Type Reference ​

TimelineAxis ​

Axis configuration for Timeline.Viewport.

FieldTypeDescription
guidesTimelineGuide[]Vertical boundary lines rendered in the axis and body
levelsTimelineAxisLevel[]Stacked header levels rendered above the body
classNamestringOptional 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[])
FieldTypeDefaultDescription
kind"spans" | "ticks"—Level rendering mode
itemsTimelineAxisSpan[] | TimelineAxisTick[]—Items to render in this level
heightnumber28Height of this axis level in pixels
classNamestring—Optional class applied to the level container

TimelineGuide ​

A vertical guide line rendered in both the axis and the body.

FieldTypeDescription
atDate | numberTime position for the guide line
keyReact.KeyOptional stable React key
axisClassNamestringOptional class for the axis portion of the guide
axisStyleCSSPropertiesOptional style for the axis portion of the guide
bodyClassNamestringOptional class for the body portion of the guide
bodyStyleCSSPropertiesOptional style for the body portion of the guide

TimelineDecorations ​

Decorative layers rendered by Timeline.Viewport.

FieldTypeDescription
bandsTimelineBand[]Background range highlights rendered behind rows
markersTimelineMarker[]Vertical markers rendered in the axis and/or body

TimelineBand ​

A decorative horizontal band rendered behind rows.

FieldTypeDescription
startDate | numberStart of the band
endDate | numberEnd of the band
keyReact.KeyOptional stable React key
colorstringOptional background color convenience prop
classNamestringOptional class applied to the band element
styleCSSPropertiesOptional inline style applied to the band

TimelineMarker ​

A decorative vertical marker line.

FieldTypeDefaultDescription
atDate | number—Time position for the marker
keyReact.Key—Optional stable React key
colorstring—Optional line color convenience prop
labelReact.ReactNode—Optional marker label
placement"axis" | "body" | "both""body"Controls where the marker is rendered
classNamestring—Optional class applied to the outer marker wrapper
lineClassNamestring—Optional class applied to the marker line
labelClassNamestring—Optional class applied to the marker label

TimelineLinkDefaults ​

Shared defaults for all Timeline.Link nodes inside one viewport.

FieldTypeDefaultDescription
routing"orthogonal""orthogonal"Link routing strategy
arrowbooleantrueWhether links end with an arrow marker
gapnumber16Horizontal gap in px used when routing out of/into items
strokeWidthnumber—Optional default stroke width for link paths
classNamestring—Optional class applied to each link SVG
styleCSSProperties—Optional style applied to each link SVG

TimelineRowBackground ​

Background content for a row rendered in a dedicated layer (in front of bands, behind guides).

FieldTypeDescription
classNamestringOptional class applied to the background layer element
styleCSSPropertiesOptional 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>
  );
}

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>
  );
}