Timeline

npx shadcn@latest add "@assistant-ui/elements-timeline"

npx assistant-ui@latest init

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/ai-sdk";

export default function App() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {/* your components */}
    </AssistantRuntimeProvider>
  );
}

npx shadcn@latest add "@assistant-ui/elements-timeline"

A sequence of events on a vertical axis, each dated, joined by a connecting line that runs solid through the past and turns hollow once it crosses into the future. With a runtime the events come from a tool result; standalone you hold the event list yourself.

Getting started

"use client";

import { defineToolkit } from "@assistant-ui/react";
import { Timeline } from "@/components/assistant-ui/elements/timeline";

export const toolkit = defineToolkit({
  get_incident_timeline: {
    type: "backend",
    render: ({ args, result }) => {
      if (!result) return <p>Loading the timeline for {args.issueId}…</p>;
      return (
        <Timeline
          events={result.events}
          visibleCount={result.events.length}
        />
      );
    },
  },
});

import {
  AssistantRuntimeProvider,
  AuiConfig,
  Tools,
} from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/ai-sdk";
import { toolkit } from "./toolkit";

export function MyRuntimeProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  const runtime = useChatRuntime();
  const config = AuiConfig({ tools: Tools({ toolkit }) });
  return (
    <AssistantRuntimeProvider runtime={runtime} config={config}>
      {children}
    </AssistantRuntimeProvider>
  );
}

"use client";

import {
  Timeline,
  type TimelineEvent,
} from "@/components/assistant-ui/elements/timeline";

const events: readonly TimelineEvent[] = [
  { id: "1", when: "past", time: "09:02", title: "Issue filed" },
  { id: "2", when: "past", time: "09:40", title: "Reproduced" },
  { id: "3", when: "now", time: "10:15", title: "Fix in review" },
  { id: "4", when: "future", time: "11:00", title: "Release 0.14.1" },
];

export function IssueTimeline() {
  return <Timeline events={events} visibleCount={events.length} />;
}

"use client";

import { useEffect, useState } from "react";

export function IssueTimeline() {
  const [visibleCount, setVisibleCount] = useState(0);

  useEffect(() => {
    if (visibleCount >= events.length) return;
    const id = setTimeout(() => setVisibleCount((n) => n + 1), 600);
    return () => clearTimeout(id);
  }, [visibleCount]);

  return <Timeline events={events} visibleCount={visibleCount} />;
}

Anatomy

<div data-slot="timeline">
  {/* one row per visible event, in array order */}
  <span>{/* event.time, right aligned */}</span>
  <span>
    {/* dot, styled by event.when */}
    {/* connector down to the next row, omitted after the last visible row */}
  </span>
  <div>
    <span>{/* event.title */}</span>
    <span>{/* optional event.detail */}</span>
  </div>
</div>

visibleCount is floored and clamped into 0…events.length the same way it is on the other structured output elements: NaN or a negative number maps to 0, and any value past the array length maps to the array length. Rows render in whatever order you pass events; the component never sorts by time or by when. The connecting line after the last visible row is omitted, so a partial reveal never trails a dangling line past the last shown dot. A dot and its connector are colored only by that event's own when: "now" fills solid blue with a ring around it, "past" fills solid gray, and "future" is a hollow outline with a dimmer connecting segment; position in the list plays no part.

Examples

Past, now, and future

Only one event in a timeline should usually carry "now", since it is the only value that bolds the title and adds the ring around the dot. Nothing in the component enforces that; you decide which event, if any, is current.

const events: readonly TimelineEvent[] = [
  { id: "1", when: "past", time: "Mon", title: "Kickoff" },
  { id: "2", when: "now", time: "Wed", title: "In progress" },
  { id: "3", when: "future", time: "Fri", title: "Due" },
];

Where the events come from

get_incident_timeline: tool({
  description: "Look up the timeline of a tracked issue.",
  inputSchema: z.object({ issueId: z.string() }),
  execute: async ({ issueId }) => getIssueTimeline(issueId),
}),

async function loadTimeline(issueId: string) {
  const { events: nextEvents } = await fetchIssueTimeline(issueId);
  setEvents(nextEvents);
  setVisibleCount(0);
}

Restyle the timeline

Both lanes take className on the root. The time column uses the shared mono surface from surfaces.tsx, so restyling that token restyles every element that uses it.

<Timeline className="max-w-none gap-0" /* ... */ />

API reference