Conversation map

Installation

npx shadcn@latest add "@assistant-ui/conversation-map"

First time? Set up a runtime

Runtime components read their state from an assistant-ui runtime. Add one to an existing project:

npx assistant-ui@latest init

Then wrap your app in a runtime provider:

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

The installation guide covers new projects, templates, and API routes.

Usage

import { ConversationMapAui } from "@/components/assistant-ui/elements/conversation-map.aui";

// A direct child of the viewport, so the rail lands in the gutter
// beside the centered message column. Hide it where there is no gutter.
<ThreadPrimitive.Viewport>
  <ConversationMapAui className="max-sm:hidden" />
  <div className="mx-auto w-full max-w-3xl">
    <ThreadPrimitive.Messages components={{ Message }} />
  </div>
</ThreadPrimitive.Viewport>

Props

ConversationMapAui

side"left" | "right"= "left": Which gutter the rail sits in. The hover preview opens toward the messages.
className?string: Classes for the sticky rail wrapper, for example to hide the map below a breakpoint.

ConversationMap

entriesConversationMapEntry[]: One tick per turn, in thread order, each with the title and preview its card shows.
activeId?string: The turn currently being read, drawn as the one solid tick.
visibleIds?string[]: Every turn the viewport holds, drawn deeper than the rest and fanned out by length once the rail is pointed at.
onSelect?(id: string) => void: Called with the turn a tick was clicked for.
side"left" | "right"= "right": Which side of the rail the preview card opens on.