# Timeline

> Tasks over days joined by what they wait for: drag one and the tasks behind it are pushed along on springs, their lines stretching like rubber bands.

Gantt charts move one bar at a time: you drag a task and only later find what it pushed, or what it ran into. Timeline shows the knock-on as you make it. Drag a task along the days and it follows your pointer, while the tasks waiting on it are pushed along on springs, each a beat behind the one before, so the dependency lines stretch like rubber bands and the delay visibly travels down the plan. A task pinned to its date doesn’t budge: its line pulls taut and turns red, so you see the clash before you let go. Drag a task’s right edge to change how long it takes and the same push follows. Release and everything snaps to whole days and settles; the critical path, the chain that sets the end date, is lit in your colour. Plain data in and out: tasks with a start date, a length, what they wait for and whether they’re pinned, and the whole plan back after every move.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/timeline.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): none
- Docs and live preview: https://hairlineui.com/ui/timeline
- Registry item (source): https://hairlineui.com/r/timeline.json

## Usage

```tsx
import { Timeline } from "@/components/timeline";

<Timeline
  title="Launch"
  tasks={[
    { id: "design", title: "Design", start: "2026-11-19", days: 4 },
    { id: "build", title: "Build", start: "2026-11-23", days: 6, after: ["design"] },
    { id: "launch", title: "Launch", start: "2026-12-03", days: 1, after: ["build"], locked: true },
  ]}
  onTasksChange={setTasks}
/>
```

## Saved to your project

Keep the plan in state, show it at once, and save the tasks whose dates changed.

```tsx
"use client";
import * as React from "react";
import { Timeline, type TimelineTask } from "@/components/timeline";

export function ProjectPlan({ initial, projectId }: { initial: TimelineTask[]; projectId: string }) {
  const [tasks, setTasks] = React.useState(initial);
  return (
    <Timeline
      title="Plan"
      tasks={tasks}
      today={new Date().toISOString().slice(0, 10)}
      onTasksChange={(next) => {
        const changed = next.filter((t, i) => t.start !== tasks[i].start || t.days !== tasks[i].days);
        setTasks(next);
        fetch(`/api/projects/${projectId}/tasks`, { method: "PATCH", body: JSON.stringify(changed) });
      }}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tasks` | `TimelineTask[]` | – | Each task: id, title, start (YYYY-MM-DD), days, and optionally after (ids it waits for), locked and group. |
| `onTasksChange` | `(tasks) => void` | – | The whole plan after a move settles. |
| `title` | `string` | `"Plan"` | Over the timeline. |
| `from / span` | `string / number` | – | The first day shown and how many days; by default two days before the first task to a week after the last. |
| `today` | `string` | – | Draws a Today line on that day. |
| `locale` | `string` | `"en-US"` | For day and month names; dates are read and written in UTC so they never shift. |

## States

- **drag**: The task follows the pointer exactly; each task waiting on it (directly or down the chain) aims where it would have to start and moves there on a spring that gets softer the further down the chain it is, so the push arrives a beat later at each step and the lines stretch and relax.
- **clash**: A pinned task never moves. When something it waits for ends after it starts, the line between them pulls straight and turns red.
- **resize**: Dragging a task’s right edge changes its length; the tasks after it are pushed the same way.
- **release**: Everything snaps to whole days on its spring; tasks are only ever pushed later, never pulled back. The plan is passed to onTasksChange and the change is announced.
- **critical path**: Tasks on the chain that ends on the last day get a ring in their colour, and the lines between them turn your primary colour.
- **reduced motion**: Tasks jump to their places; nothing trails.

## What it handles

A Gantt chart moves one bar at a time, so what a delay pushes, and what it runs into, only shows after you let go.

- **The knock-on, live**: Dependent tasks are pushed along on springs as you drag, each a beat behind.
- **Clashes as you make them**: A pinned task’s line pulls taut and turns red before you let go.
- **Length by the edge**: Drag a task’s right edge to change its length; the push follows.
- **The critical path**: The chain that sets the end date is lit after every move.
- **Plain dates in and out**: YYYY-MM-DD starts and day counts; the whole plan back on each change.
- **Keyboard**: Arrows move a task a day; Shift with them changes its length.

## Replaces

a gantt chart, a project timeline, a roadmap view, dependency arrows, a critical path view

## Where it fits

- **Roadmaps**: Quarters of work by team, with what has to land first.
- **Launch plans**: Design, build, QA and launch day, pinned.
- **Client projects**: An agency plan the client can see shift when a phase slips.
- **Event and content planning**: Bookings, drafts and deadlines that wait on each other.

## Notes

- Each task is a focusable bar named with its dates, length, and whether it’s pinned or on the critical path; ← → move it a day, Shift with them change its length; moves are announced politely.
- Bars move by transform from one spring each (createSpring from ui-interaction-motion.ts, installed with it), and the lines are redrawn from the springs in one frame loop; nothing re-renders during a drag.
- Tasks are only pushed later by what they wait for, never pulled earlier, so dragging something back leaves the plan as it was.
- Scrolls sideways on narrow screens. With reduced motion tasks jump to their places.

License: MIT (https://hairlineui.com/license#components)
