# Animated Timeline for UI SDK (/docs/components/timeline)

Events rise in one after another, a finished step's check draws itself and the rail fills.

```tsx title="example.tsx"
import * as React from "react"

import {
  Timeline,
  TimelineConnector,
  TimelineDescription,
  TimelineItem,
  TimelineMarker,
  TimelineTime,
  TimelineTitle,
} from "@/components/keyframery/timeline"

const stages = [
  { value: "ordered", title: "Order placed", time: "Mon 9:14", description: "Linen throw, oat · 1 item" },
  { value: "packed", title: "Packed", time: "Mon 16:02", description: "Left our Leeds warehouse" },
  { value: "transit", title: "In transit", time: "Tue 7:40", description: "At the Manchester depot" },
  { value: "out", title: "Out for delivery", time: "Wed", description: "Driver arrives 10:00 to 12:00" },
  { value: "delivered", title: "Delivered", time: "Wed", description: "Leave with a neighbour if out" },
]

export default function TimelineDemo() {
  const [current, setCurrent] = React.useState(2)
  const [parcel, setParcel] = React.useState(0)
  const finished = current >= stages.length

  return (
    <div className="w-[380px]">
      <div className="mb-5 flex items-start justify-between gap-4">
        <div>
          <h3 className="text-[15px] font-semibold tracking-tight">
            {finished ? "Delivered" : "Arriving Wednesday"}
          </h3>
          <p className="mt-1 text-[13px] text-muted-foreground tabular-nums">
            Parcel {4821 + parcel} · Royal Mail
          </p>
        </div>
        <button
          type="button"
          data-slot="timeline-refresh"
          onClick={() => {
            if (finished) {
              setParcel((n) => n + 1)
              setCurrent(1)
            } else setCurrent((step) => step + 1)
          }}
          className="inline-flex h-7 cursor-pointer items-center rounded-[8px] bg-background px-2.5 text-[12px] font-medium shadow-[0_0_0_1px_rgb(0_0_0/0.06),0_1px_1px_rgb(0_0_0/0.05),0_3px_6px_-2px_rgb(0_0_0/0.1)] transition-[translate,scale,opacity] duration-100 outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background active:translate-y-px active:scale-[0.985] dark:bg-accent dark:shadow-[0_0_0_1px_rgb(255_255_255/0.07),inset_0_1px_0_rgb(255_255_255/0.08),0_2px_6px_-1px_rgb(0_0_0/0.6)]"
        >
          {finished ? "Track next" : "Refresh"}
        </button>
      </div>
      <Timeline key={parcel} aria-label="Delivery progress">
        {stages.map((stage, index) => (
          <TimelineItem
            key={stage.value}
            value={stage.value}
            status={index < current ? "complete" : index === current ? "current" : "upcoming"}
          >
            <TimelineMarker />
            <TimelineConnector />
            <TimelineTitle>{stage.title}</TimelineTitle>
            <TimelineTime>{stage.time}</TimelineTime>
            <TimelineDescription>{stage.description}</TimelineDescription>
          </TimelineItem>
        ))}
      </Timeline>
    </div>
  )
}
```

## Installation [#installation]

```bash
npx shadcn@latest add @keyframery/timeline
```

This adds `components/keyframery/timeline.tsx` and its primitive, `components/keyframery/primitives/timeline.tsx`, to your project, and installs `@ui-sdk/react`. The motion tokens are added to your global CSS the first time you install a component.

## Usage [#usage]

```tsx
import {
  Timeline,
  TimelineConnector,
  TimelineDescription,
  TimelineItem,
  TimelineMarker,
  TimelineTime,
  TimelineTitle,
} from "@/components/keyframery/timeline"
```

The parts and props are the same as UI SDK's Timeline. For every prop, see the [UI SDK timeline reference](https://ui-sdk.dev/docs/components/timeline).

## What moves [#what-moves]

| Move        | What you see                          |
| ----------- | ------------------------------------- |
| **Cascade** | Events rise in one after another.     |
| **Draw**    | A finished step's check draws itself. |
| **Spring**  | The rail fills as steps complete.     |

Timing and springiness follow the [motion style](/docs/motion-styles) you set, so this component moves like the rest of your app.

## Swap the import [#swap-the-import]

Already using UI SDK's timeline with your own styles? Keep your markup and change one line. The primitive adds motion and nothing else.

```tsx
// Before
import { … } from "@ui-sdk/react/timeline"

// After: same parts, same props, now animated
import { … } from "@/components/keyframery/primitives/timeline"
```

## Parts [#parts]

The finished component exports 7 parts:

`Timeline`, `TimelineConnector`, `TimelineDescription`, `TimelineItem`, `TimelineMarker`, `TimelineTime`, `TimelineTitle`

## Accessibility [#accessibility]

Keyboard, focus and screen-reader behaviour come from UI SDK and are not changed. With reduced motion turned on, nothing in the timeline moves: changes happen at once or with a short fade. More in [Accessibility](/docs/accessibility).

## Source [#source]

The code that lands in your project. It is yours to change.

**components/keyframery/timeline.tsx**

```tsx
"use client"

/* Styled timeline: the animated primitive plus the Keyframery look. */

import * as React from "react"

import {
  Timeline as TimelineRoot,
  TimelineConnector as TimelineConnectorPart,
  TimelineDescription as TimelineDescriptionPart,
  TimelineItem as TimelineItemPart,
  TimelineMarker as TimelineMarkerPart,
  TimelineTime as TimelineTimePart,
  TimelineTitle as TimelineTitlePart,
  createTimelineController,
} from "@/components/keyframery/primitives/timeline"
import { cn } from "@/lib/utils"

/* The events, one above the other, or side by side in a row of equal columns. */
function Timeline({ className, ...props }: React.ComponentProps<typeof TimelineRoot>) {
  return (
    <TimelineRoot
      className={cn(
        "flex flex-col text-[13px]",
        "data-[orientation=horizontal]:grid data-[orientation=horizontal]:grid-cols-[repeat(var(--timeline-count,1),minmax(0,1fr))]",
        "data-busy:opacity-70",
        className,
      )}
      {...props}
    />
  )
}

/* One event. The marker has its own column and the text sits beside it. The primitive
   cascades the events in when the timeline first appears. */
function TimelineItem({ className, ...props }: React.ComponentProps<typeof TimelineItemPart>) {
  return (
    <TimelineItemPart
      className={cn(
        "relative -mx-2 grid grid-cols-[20px_minmax(0,1fr)_auto] content-start gap-x-3 rounded-[10px] px-2 pt-1.5 pb-4 outline-none last:pb-1.5",
        "data-[orientation=horizontal]:mx-0 data-[orientation=horizontal]:grid-cols-[minmax(0,1fr)] data-[orientation=horizontal]:px-0 data-[orientation=horizontal]:pr-4 data-[orientation=horizontal]:pb-1.5",
        "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
        className,
      )}
      {...props}
    />
  )
}

/* The dot on the rail. A plain event is a small dot; an upcoming step is hollow; the
   current step is a primary key; a finished step turns the one success green, and the
   primitive pops it and draws its check. */
function TimelineMarker({
  className,
  children,
  ...props
}: React.ComponentProps<typeof TimelineMarkerPart>) {
  return (
    <TimelineMarkerPart
      className={cn(
        "relative col-start-1 [--kf-draw:11] row-start-1 grid size-5 place-items-center self-start",
        "data-[orientation=horizontal]:mb-2.5",
        /* The dot itself, drawn behind any icon. */
        "before:absolute before:top-1/2 before:left-1/2 before:size-2 before:-translate-1/2 before:rounded-full before:bg-muted-foreground/45",
        "before:transition-[width,height,background-color,box-shadow] before:duration-[calc(200ms*var(--kf-speed,1))] before:ease-house",
        "data-upcoming:before:size-2.5 data-upcoming:before:bg-background data-upcoming:before:shadow-[inset_0_0_0_1.5px_color-mix(in_oklab,var(--foreground)_24%,transparent)]",
        "data-current:before:size-4 data-current:before:bg-primary",
        "data-current:before:shadow-[inset_0_1px_0_rgb(255_255_255/0.14),0_1px_2px_rgb(0_0_0/0.25),0_0_0_4px_color-mix(in_oklab,var(--primary)_10%,transparent)]",
        "dark:data-current:before:shadow-[inset_0_1px_0_rgb(255_255_255/0.7),0_1px_2px_rgb(0_0_0/0.5),0_0_0_4px_color-mix(in_oklab,var(--primary)_14%,transparent)]",
        "data-complete:before:size-4 data-complete:before:bg-[oklch(0.62_0.16_150)] data-complete:before:shadow-[inset_0_1px_0_rgb(255_255_255/0.2),0_1px_2px_rgb(0_0_0/0.2)]",
        /* The current step's centre. */
        "after:absolute after:top-1/2 after:left-1/2 after:size-0 after:-translate-1/2 after:rounded-full after:bg-primary-foreground after:transition-[width,height] after:duration-[calc(200ms*var(--kf-speed,1))]",
        "data-current:after:size-1.5",
        "[&_svg]:relative [&_svg]:size-3 [&_svg]:text-white",
        "motion-reduce:before:transition-none! motion-reduce:after:transition-none!",
        className,
      )}
      {...props}
    >
      {children ??
        ((state) =>
          state.status === "complete" && (
            <svg
              viewBox="0 0 16 16"
              fill="none"
              stroke="currentColor"
              strokeWidth="2"
              strokeLinecap="round"
              strokeLinejoin="round"
              aria-hidden
            >
              <path d="m4.5 8.25 2.25 2.25 4.75-5" />
            </svg>
          ))}
    </TimelineMarkerPart>
  )
}

/* The hairline from this event's marker down to the next one. Past a finished step the
   primitive fills it, so the rail reads as travelled. The last event has none. */
function TimelineConnector({
  className,
  ...props
}: React.ComponentProps<typeof TimelineConnectorPart>) {
  return (
    <TimelineConnectorPart
      className={cn(
        "pointer-events-none absolute top-[30px] -bottom-1 left-[17.5px] w-px rounded-full bg-border",
        "after:bg-foreground/30",
        "data-[orientation=horizontal]:top-[15.5px] data-[orientation=horizontal]:right-1 data-[orientation=horizontal]:bottom-auto data-[orientation=horizontal]:left-6 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-auto",
        "in-data-last:hidden",
        className,
      )}
      {...props}
    />
  )
}

function TimelineTitle({ className, ...props }: React.ComponentProps<typeof TimelineTitlePart>) {
  return (
    <TimelineTitlePart
      className={cn(
        "col-start-2 row-start-1 min-w-0 self-center leading-5 font-medium text-foreground",
        "data-upcoming:text-muted-foreground data-current:font-semibold",
        "data-[orientation=horizontal]:col-start-1 data-[orientation=horizontal]:row-start-2",
        className,
      )}
      {...props}
    />
  )
}

function TimelineTime({ className, ...props }: React.ComponentProps<typeof TimelineTimePart>) {
  return (
    <TimelineTimePart
      className={cn(
        "col-start-3 row-start-1 self-center text-[12px] leading-5 whitespace-nowrap text-muted-foreground tabular-nums",
        "data-[orientation=horizontal]:col-start-1 data-[orientation=horizontal]:row-start-3",
        className,
      )}
      {...props}
    />
  )
}

function TimelineDescription({
  className,
  ...props
}: React.ComponentProps<typeof TimelineDescriptionPart>) {
  return (
    <TimelineDescriptionPart
      className={cn(
        "col-span-2 col-start-2 row-start-2 mt-0.5 text-[13px] leading-[18px] text-muted-foreground",
        "data-upcoming:text-muted-foreground/80",
        "data-[orientation=horizontal]:col-span-1 data-[orientation=horizontal]:col-start-1 data-[orientation=horizontal]:row-start-4",
        className,
      )}
      {...props}
    />
  )
}

export {
  Timeline,
  TimelineConnector,
  TimelineDescription,
  TimelineItem,
  TimelineMarker,
  TimelineTime,
  TimelineTitle,
  createTimelineController,
}
```

**components/keyframery/primitives/timeline.tsx**

```tsx
"use client"

/* Animated drop-in for `@ui-sdk/react/timeline`: same parts, same props. Swap the import and keep your code.
   This file adds motion only. Colours, radii, shadows and spacing stay yours.

   - Cascade: events rise in one after another, with a blur, when the timeline first appears.
   - Draw: when a step completes, its marker pops and the strokes of its icon draw themselves. Set
     `--kf-draw` on the marker to your icon's path length (24 by default, right for a 24px check).
   - The rail fills: a finished step's connector fills from its marker toward the next one. The fill is
     the connector's `after:`; give it your own colour with `after:` classes. */

import {
  TimelineConnector as TimelineConnectorPart,
  TimelineItem as TimelineItemPart,
  TimelineMarker as TimelineMarkerPart,
} from "@ui-sdk/react/timeline"
import * as React from "react"

import { cn } from "@/lib/utils"

export * from "@ui-sdk/react/timeline"

const keyframes =
  "@keyframes kf-timeline-pop{from{scale:.6}}" +
  "@keyframes kf-timeline-draw{from{stroke-dashoffset:var(--kf-draw,24)}to{stroke-dashoffset:0}}"

/* Only opacity, translate and filter transition here, so the stagger never slows anything else. */
function TimelineItem({ className, ...props }: React.ComponentProps<typeof TimelineItemPart>) {
  return (
    <TimelineItemPart
      className={cn(
        "transition-[opacity,translate,filter] duration-[calc(420ms*var(--kf-speed,1))] ease-spring [transition-delay:calc((min(sibling-index(),10)-1)*calc(32ms*var(--kf-speed,1)))]",
        "starting:translate-y-2 starting:opacity-0 starting:blur-[4px]",
        "motion-reduce:transition-none!",
        className,
      )}
      {...props}
    />
  )
}

function TimelineMarker({ className, ...props }: React.ComponentProps<typeof TimelineMarkerPart>) {
  return (
    <>
      <style href="kf-timeline" precedence="default">
        {keyframes}
      </style>
      <TimelineMarkerPart
        className={cn(
          "motion-reduce:animate-none! motion-reduce:[&_path]:animate-none! data-complete:animate-[kf-timeline-pop_calc(420ms*var(--kf-speed,1))_var(--ease-pop)]",
          "data-complete:[&_path]:[stroke-dasharray:var(--kf-draw,24)] data-complete:[&_path]:animate-[kf-timeline-draw_calc(260ms*var(--kf-speed,1))_var(--ease-house)_calc(140ms*var(--kf-speed,1))_both]",
          "motion-reduce:animate-none! motion-reduce:[&_path]:animate-none",
          className,
        )}
        {...props}
      />
    </>
  )
}

/* The fill grows along the connector once its step is complete, a moment after the check. */
function TimelineConnector({ className, ...props }: React.ComponentProps<typeof TimelineConnectorPart>) {
  return (
    <TimelineConnectorPart
      className={cn(
        "overflow-hidden",
        "after:absolute after:inset-0 after:origin-top after:scale-y-0 after:content-['']",
        "after:bg-[color-mix(in_oklch,currentColor_35%,transparent)]",
        "data-[orientation=horizontal]:after:origin-left data-[orientation=horizontal]:after:scale-x-0 data-[orientation=horizontal]:after:scale-y-100",
        "data-complete:after:scale-100",
        "after:transition-[scale] after:delay-[calc(200ms*var(--kf-speed,1))] after:duration-[calc(600ms*var(--kf-speed,1))] after:ease-house motion-reduce:after:transition-none!",
        className,
      )}
      {...props}
    />
  )
}

export { TimelineConnector, TimelineItem, TimelineMarker }
```

## Questions

### How does the animated Timeline for UI SDK move?

Cascade: Events rise in one after another. Draw: A finished step's check draws itself. Spring: The rail fills as steps complete.

### Do I need Motion or Framer Motion for the animated Timeline?

No. Every move is plain CSS, so there is nothing to install besides the component and UI SDK.

### Can I keep my own styling and only take the motion?

Yes. Import from `@/components/keyframery/primitives/timeline` instead. It has the same parts and props as `@ui-sdk/react/timeline` and adds motion only.

### What happens to the Timeline when someone turns on reduced motion?

Nothing moves. State changes happen at once, or with a short fade.
