Thread List Component

Sidebar or dropdown component for switching between AI chat conversations. Persistent thread state, search, and active selection — built for assistant-ui apps.

How can I help you today?

This demo uses ThreadListSidebar, which includes thread-list as a dependency and provides a complete sidebar layout. For custom implementations, you can use thread-list directly.

Getting Started

Add the component

Use threadlist-sidebar for a complete sidebar layout or thread-list for custom layouts.

ThreadListSidebar

npx shadcn@latest add @assistant-ui/threadlist-sidebar

The @assistant-uinamespace resolves the Radix or Base UI flavor from your project's style through the style-aware registry entry in components.json. Without that entry, add by direct URL instead:

npx shadcn@latest add https://r.assistant-ui.com/base/threadlist-sidebar.json

ThreadList

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

The @assistant-uinamespace resolves the Radix or Base UI flavor from your project's style through the style-aware registry entry in components.json. Without that entry, add by direct URL instead:

npx shadcn@latest add https://r.assistant-ui.com/base/thread-list.json

Use in your application

/app/assistant.tsx
import { Thread } from "@/components/assistant-ui/thread";
import { ThreadListSidebar } from "@/components/assistant-ui/threadlist-sidebar";
import {
  SidebarProvider,
  SidebarInset,
  SidebarTrigger
} from "@/components/ui/sidebar";

export default function Assistant() {
  return (
    <SidebarProvider>
      <div className="flex h-dvh w-full">
        <ThreadListSidebar />
        <SidebarInset>
          {/* Add sidebar trigger, location can be customized */}
          <SidebarTrigger className="absolute top-4 left-4" />
          <Thread />
        </SidebarInset>
      </div>
    </SidebarProvider>
  );
}

Anatomy

The ThreadList component is built with the following primitives:

import { ThreadListPrimitive, ThreadListItemPrimitive } from "@assistant-ui/react";

<ThreadListPrimitive.Root>
  <ThreadListPrimitive.New />
  <ThreadListPrimitive.Items>
    {() => (
      <ThreadListItemPrimitive.Root>
        <ThreadListItemPrimitive.Trigger>
          <ThreadListItemPrimitive.Title />
        </ThreadListItemPrimitive.Trigger>
        <ThreadListItemPrimitive.Archive />
        <ThreadListItemPrimitive.Delete />
      </ThreadListItemPrimitive.Root>
    )}
  </ThreadListPrimitive.Items>
</ThreadListPrimitive.Root>

API Reference

ThreadListPrimitive.Root

Container for the thread list.

ThreadListPrimitiveRootProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper div.

ThreadListPrimitive.Items

Renders all threads in the list.

ThreadListPrimitiveItemsProps
archived ?: boolean

When true, renders archived threads instead of active threads.

components : object

Component configuration.

ThreadListItem : ComponentType

Component to render for each thread item.

ThreadListPrimitive.New

A button to create a new thread.

ThreadListPrimitiveNewProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper button.

ThreadListPrimitive.LoadMore

A button that appends the next page of threads. See the LoadMore primitive reference for usage and Threads concepts for the adapter contract.

ThreadListPrimitiveLoadMoreProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper button.

ThreadListItemPrimitive.Root

Container for a single thread item. Automatically sets data-active and aria-current when this is the current thread.

ThreadListItemPrimitiveRootProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper div.

ThreadListItemPrimitive.Trigger

A button that switches to this thread when clicked.

ThreadListItemPrimitiveTriggerProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper button.

ThreadListItemPrimitive.Title

Renders the thread's title.

ThreadListItemPrimitiveTitleProps
fallback ?: ReactNode

Content to display when the thread has no title.

ThreadListItemPrimitive.Archive

A button to archive the thread.

ThreadListItemPrimitiveArchiveProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper button.

ThreadListItemPrimitive.Unarchive

A button to restore an archived thread.

ThreadListItemPrimitiveUnarchiveProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper button.

ThreadListItemPrimitive.Delete

A button to permanently delete the thread.

ThreadListItemPrimitiveDeleteProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper button.

ThreadListItemMorePrimitive

A dropdown menu for additional thread actions, built on Radix UI DropdownMenu.

ThreadListItemMorePrimitive.Root

Menu container that manages dropdown state.

ThreadListItemMorePrimitiveRootProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper div.

ThreadListItemMorePrimitive.Trigger

Button to open the menu.

ThreadListItemMorePrimitiveTriggerProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper button.

ThreadListItemMorePrimitive.Content

Menu content container.

ThreadListItemMorePrimitiveContentProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper div.

ThreadListItemMorePrimitive.Item

Individual menu item.

ThreadListItemMorePrimitiveItemProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper div.

ThreadListItemMorePrimitive.Separator

Visual separator between items.

ThreadListItemMorePrimitiveSeparatorProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper div.

  • Thread - The main chat interface displayed alongside the list