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[] = [
  { title: "Renaming a component", time: "2m", unread: true },
  { 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 actually 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. Its rename and delete icons are presentational: they render on hover but carry no click handler, since this file is copied into your project specifically so you attach your own.

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

Restyle

Both lanes take className on the root. Standalone, the active row's fill and the 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