Thread list

npx shadcn@latest add "@assistant-ui/thread-list"

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-thread-list"

Thread list is the conversation switcher: a new-thread button, search once there is something to search, and every past thread grouped by day with rename, archive, and delete. With a runtime it reads and writes the thread list directly; standalone you pass in the rows and report which one is active.

Getting started

import { ThreadList } from "@/components/assistant-ui/elements/thread-list.aui";

export function Sidebar() {
  return (
    <aside className="w-64 border-e p-2">
      <ThreadList />
    </aside>
  );
}

"use client";

import { useState } from "react";
import {
  ThreadList,
  type ThreadItem,
} from "@/components/assistant-ui/elements/thread-list";

const threads: ThreadItem[] = [
  { id: "rename", title: "Renaming a component", time: "2m", unread: true },
  { id: "deploy", title: "Deploy checklist", time: "1h" },
];

export function Sidebar() {
  const [activeIndex, setActiveIndex] = useState(0);
  return (
    <ThreadList
      threads={threads}
      activeIndex={activeIndex}
      onActiveIndexChange={setActiveIndex}
    />
  );
}

Anatomy

<div data-slot="aui_thread-list-root">
  <button data-slot="aui_thread-list-new">New Thread</button>
  <div data-slot="aui_thread-list-search" /> {/* runtime only, once a thread exists */}
  <div data-slot="aui_thread-list-items">
    <div data-slot="aui_thread-list-group-label">Today</div>
    <div data-slot="aui_thread-list-item">
      <button data-slot="aui_thread-list-item-trigger">
        {/* spinner while running, then the title */}
      </button>
      <button data-slot="aui_thread-list-item-more" aria-label="More options" />
    </div>
  </div>
</div>

Runtime, the search box only renders once at least one thread exists, and it filters case-insensitively against each thread's title, falling back to matching "New Chat" for untitled ones; no match shows "No threads found" instead of the list. Rows group under Today, Yesterday, and Earlier by lastMessageAt, but only when at least one visible thread carries a timestamp, otherwise the list renders flat with no group labels. The active thread carries data-active and aria-current. Rename swaps a row's trigger for an inline input in place (Enter commits, Escape cancels, blur commits); it never navigates away from the list.

Standalone, the element renders a single static "Today" label above every row regardless of the actual dates, since it has no timestamps to group by, and it has no new-thread control or search of its own. Rename and delete are controlled actions: each button renders only when its matching callback is provided.

Examples

Search

<ThreadList
  threads={threads.filter((t) =>
    t.title.toLowerCase().includes(query.toLowerCase()),
  )}
  activeIndex={activeIndex}
  onActiveIndexChange={setActiveIndex}
/>

Renaming

const aui = useAui();
aui.threads.item({ id: threadId }).rename("Q3 planning");

<ThreadList
  threads={threads}
  activeIndex={activeIndex}
  onActiveIndexChange={setActiveIndex}
  onRename={(index) => setRenamingIndex(index)}
  onDelete={(index) => {
    setThreads((current) => current.filter((_, i) => i !== index));
    setActiveIndex((current) =>
      Math.max(0, current - Number(index <= current)),
    );
  }}
/>

Restyle

Standalone, ThreadList takes className on the root; the runtime ThreadList takes no props, so size it from a wrapper element. The standalone active row's fill and trailing timestamp use the shared field and mono tokens from surfaces.tsx, so restyling those two tokens restyles every element that uses them.

<ThreadList className="max-w-[280px]" /* ... */ />

API reference