OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add assistant-ui/skills --skill thread-list
Builds and customizes multiple conversation lists in assistant-ui with the runtime connected ThreadList and ThreadListSidebar elements, ThreadListPrimitive, ThreadListItemPrimitive, ThreadListItemMorePrimitive, useAui, useAuiState, and threads.selectionChanged. Use when adding a conversation sidebar, switching, archiving, renaming, deleting, searching, grouping, paginating, or persisting threads, or when thread state is stale after authentication. Covers AssistantCloud, RemoteThreadListRuntime, and ExternalStoreThreadListAdapter. Use runtime for the active conversation runtime, cloud for managed authentication and persistence, and elements for registry installation and styling.
npx skills add assistant-ui/skills --skill thread-list
Always consult assistant-ui.com/llms.txt for the latest API.
A runtime starts with one in memory conversation. Add a thread list only when people need to create, select, and manage multiple conversations. Choose the managed cloud path, a backend adapter, or an external store before choosing the UI.
Install the runtime connected list with npx assistant-ui@latest add thread-list. It creates components/assistant-ui/elements/thread-list.aui.tsx. Pass an AssistantCloud instance to useChatRuntime for managed threads, then render the list and active thread beneath the provider.
Use the full sidebar shell when the project already uses the shadcn sidebar primitives. ThreadListSidebar renders the runtime connected thread list itself, so do not also mount ThreadList inside it.
ThreadListSidebar still needs the AssistantRuntimeProvider ancestor from the first example. Its SidebarProvider is separate layout context.
Use useAui() for commands. Scope accessors are properties, so use aui.threads and aui.threadListItem, never aui.threads(). Read each state value independently with useAuiState. A selector may return one primitive value or a stable runtime reference, but never an object or array literal.
Inside a thread item primitive, s.threadListItem is the item in scope. Select fields individually, not the whole state object, when a row only needs one value.
Start from the three primitive namespaces when the installed element's date grouping, search, or visual treatment does not match the product. Items supplies the current item scope and its children render function replaces the deprecated components prop.
See custom UI for archived rows, load more, custom search, grouping, keyboard behavior, and the complete part reference.
| Path | Use it when | Thread metadata lives in |
|---|---|---|
AssistantCloud | You want managed authentication, persistence, synchronization, and titles | assistant-cloud |
useRemoteThreadListRuntime with RemoteThreadListAdapter | A LocalRuntime based runtime uses the application's database | Your backend |
ExternalStoreThreadListAdapter | An ExternalStoreRuntime already owns messages and selection | Your state store |
The cloud quick start above is the managed path. The remote and external store paths have different ownership and lifecycle requirements. Follow remote adapter instead of mixing their APIs.
threads.selectionChanged replaces the old per item switch events. It runs for every selection change and supplies both IDs. It does not run for the initial selection on mount.
When this listener is inside an item row, compare threadId to s.threadListItem.id if it should react only when that row becomes current.
The list renders but no conversations persist
cloud, use a RemoteThreadListAdapter, or provide an ExternalStoreThreadListAdapter.A thread switch uses stale messages
RemoteThreadList store entry, wrap the thread factory in withKey(id, ...) so a history adapter mounts for the selected ID.backgroundThreads only when runs should continue after selection changes and retaining visited threads in memory is acceptable.The sidebar has no runtime
ThreadList and ThreadListSidebar need an AssistantRuntimeProvider ancestor.ThreadListSidebar also needs the shadcn SidebarProvider because it is a sidebar shell, not a runtime provider.Rows re render on every unrelated store change
useAuiState calls. Returning s.threads.threadIds directly is safe because it is a runtime supplied stable reference.The switch handler stopped firing after an upgrade
threads.selectionChanged and use previousThreadId. The retired threadListItem.switchedTo and threadListItem.switchedAway events are not the current integration point.import { SidebarInset, SidebarProvider } from "@/components/ui/sidebar";
import { Thread } from "@/components/assistant-ui/elements/thread.aui";
import { ThreadListSidebar } from "@/components/assistant-ui/elements/threadlist-sidebar.aui";
export function ChatLayout() {
return (
<SidebarProvider>
<ThreadListSidebar />
<SidebarInset>
<Thread />
</SidebarInset>
</SidebarProvider>
);
}import { useAui, useAuiState } from "@assistant-ui/react";
export function ThreadControls({ threadId }: { threadId: string }) {
const aui = useAui();
const activeThreadId = useAuiState((s) => s.threads.mainThreadId);
const threadIds = useAuiState((s) => s.threads.threadIds);
const isLoading = useAuiState((s) => s.threads.isLoading);
const item = aui.threads.item({ id: threadId });
return (
<div>
<p>{threadIds.length} conversations</p>
<p>{activeThreadId === threadId ? "Current" : "Available"}</p>
<button disabled={isLoading} onClick={() => aui.threads.switchToNewThread()}>
New conversation
</button>
<button onClick={() => item.switchTo()}>Open</button>
<button onClick={() => item.rename("Project planning")}>Rename</button>
<button onClick={() => item.archive()}>Archive</button>
<button onClick={() => item.delete()}>Delete</button>
</div>
);
}import { useAuiState } from "@assistant-ui/react";
export function ThreadRunningBadge() {
const isRunning = useAuiState((s) => s.threadListItem.isRunning);
return isRunning ? <span>Working</span> : null;
}import {
ThreadListItemMorePrimitive,
ThreadListItemPrimitive,
ThreadListPrimitive,
} from "@assistant-ui/react";
export function CustomThreadList() {
return (
<ThreadListPrimitive.Root className="flex flex-col gap-1">
<ThreadListPrimitive.New>New conversation</ThreadListPrimitive.New>
<ThreadListPrimitive.Items>
{({ threadListItem }) => (
<ThreadListItemPrimitive.Root data-thread-id={threadListItem.id}>
<ThreadListItemPrimitive.Trigger className="flex-1 text-left">
<ThreadListItemPrimitive.Title fallback="New conversation" />
</ThreadListItemPrimitive.Trigger>
<ThreadListItemMorePrimitive.Root sharedFocusGroup>
<ThreadListItemMorePrimitive.Trigger>
More
</ThreadListItemMorePrimitive.Trigger>
<ThreadListItemMorePrimitive.Content>
<ThreadListItemPrimitive.Archive asChild>
<ThreadListItemMorePrimitive.Item>
Archive
</ThreadListItemMorePrimitive.Item>
</ThreadListItemPrimitive.Archive>
<ThreadListItemMorePrimitive.Separator />
<ThreadListItemPrimitive.Delete asChild>
<ThreadListItemMorePrimitive.Item>
Delete
</ThreadListItemMorePrimitive.Item>
</ThreadListItemPrimitive.Delete>
</ThreadListItemMorePrimitive.Content>
</ThreadListItemMorePrimitive.Root>
</ThreadListItemPrimitive.Root>
)}
</ThreadListPrimitive.Items>
</ThreadListPrimitive.Root>
);
}import { useAuiEvent } from "@assistant-ui/react";
export function SelectionTelemetry() {
useAuiEvent(
"threads.selectionChanged",
({ threadId, previousThreadId }) => {
recordThreadSelection({ threadId, previousThreadId });
},
);
return null;
}