assistant-ui logo/Docs

ThreadList

Switch between conversations. Supports sidebar or dropdown layouts.

Hello there!

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 https://r.assistant-ui.com/threadlist-sidebar.json

ThreadList

npx shadcn@latest add https://r.assistant-ui.com/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
    components={{
      ThreadListItem: () => (
        <ThreadListItemPrimitive.Root>
          <ThreadListItemPrimitive.Trigger>
            <ThreadListItemPrimitive.Title />
          </ThreadListItemPrimitive.Trigger>
          <ThreadListItemPrimitive.Archive />
          <ThreadListItemPrimitive.Delete />
        </ThreadListItemPrimitive.Root>
      ),
    }}
  />
</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.

componentsrequired: object

Component configuration.

Components
ThreadListItemrequired: 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.

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