# Threads Drawer

> Drop-in threads drawer that lists, switches, and manages conversations next to your chat.

## What is this? [#what-is-this]

`<CopilotThreadsDrawer>` gives your app a ready-made conversation sidebar. Users can
list, switch, start, archive, and delete their threads, and you wire up
**no active-thread state** to make it work. Drop it next to your chat and it
connects automatically.

If your project was created from a CopilotKit CLI starter, the Drawer and its
shared chat configuration are already included. Otherwise, use the setup below
to add it to an existing CopilotKit application. This guide also covers Drawer
customization and component options.

<Frame description="CopilotThreadsDrawer beside a CopilotChat. Selecting a thread replays its conversation with no active-thread wiring.">
  <img
    src="/images/threads/support-desk-threads.png"
    alt="A support desk application with a Threads Drawer listing customer conversations beside CopilotChat case details for Northstar Analytics"
    className="w-full rounded-lg"
  />
</Frame>

Internally, it's a thin React wrapper around the self-contained
`copilotkit-threads-drawer` web component, fed by [`useThreads`](/reference/hooks/useThreads)
and your chat configuration.

Prefer to build your own thread UI? The same data and actions are available
headlessly through the `useThreads` hook (see
[Headless Threads](/ag2/headless-threads)). Thread **rename** is one of those headless
actions: the prebuilt drawer's row menu covers archive/unarchive and delete, so
wire up rename with `useThreads` and your own UI if you need it.

## When should I use this? [#when-should-i-use-this]

Use the drawer when you want:

- A persistent thread switcher beside your chat (chat-history sidebar)
- Thread switching, new conversations, archive, and delete with zero wiring
- A self-contained, themeable UI that follows your app's light/dark theme
- A mobile-ready off-canvas drawer with its own launcher

It requires CopilotKit Intelligence (threads are stored and synced
server-side). <SignupLink surface="docs_drawer">Start cloud-hosted setup</SignupLink> to create or select a project.

For multi-user applications, configure the Runtime to
[scope threads to the signed-in user](/ag2/threads-lifecycle#scope-rich-threads-to-the-signed-in-user).

<OpsPlatformCTA
  variant="inline"
  title="Threads run in CopilotKit Intelligence"
  body="Connect a cloud-hosted project to get persistent threads and realtime sync."
  surface="docs_drawer"
/>

## Set up the Threads Drawer [#set-up-the-threads-drawer]

Place `<CopilotThreadsDrawer>` next to [`<CopilotChat>`](/ag2/prebuilt-components/chat) and wrap **both** in a
shared `<CopilotChatConfigurationProvider>`. If you are using a CLI-created
starter, this structure is already in place. The shared configuration lets
the Drawer control the chat. Select a row, and the chat loads that thread and
its history. Select "New Conversation", and the chat shows the welcome screen.
The following example shows the essential structure to add to an existing app
or preserve while customizing a starter.

```tsx title="app/page.tsx"
import {
  CopilotKitProvider,
  CopilotChatConfigurationProvider,
  CopilotChat,
  CopilotThreadsDrawer,
} from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export default function Page() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <CopilotChatConfigurationProvider>
        <div style={{ display: "flex", height: "100dvh" }}>
          <CopilotThreadsDrawer />
          <CopilotChat />
        </div>
      </CopilotChatConfigurationProvider>
    </CopilotKitProvider>
  );
}
```

Import the Drawer, the chat, and the provider from `@copilotkit/react-core/v2`.

Start your app and send a message. After the run, the thread appears in the
Drawer. Select "New Conversation", then select the first thread. The chat
shows its history again.

## Use the Drawer with a sidebar chat [#use-the-drawer-with-a-sidebar-chat]

`<CopilotChat>` is not the only host. `<CopilotSidebar>` works the same way,
because it renders a `<CopilotChat>` inside itself and therefore shares the same
chat configuration. Keep the Drawer as a sibling of your content and put the
sidebar alongside it:

```tsx title="app/page.tsx"
import {
  CopilotKitProvider,
  CopilotChatConfigurationProvider,
  CopilotSidebar,
  CopilotThreadsDrawer,
} from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export default function Page() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <CopilotChatConfigurationProvider>
        <div style={{ display: "flex", height: "100dvh" }}>
          <CopilotThreadsDrawer />
          <main style={{ flex: 1 }}>
            <YourMainContent />
            <CopilotSidebar defaultOpen={true} />
          </main>
        </div>
      </CopilotChatConfigurationProvider>
    </CopilotKitProvider>
  );
}
```

`<CopilotPopup>` hosts the Drawer on the same terms, for the same reason.

<Callout type="info">
  The launcher button that opens the Drawer from the chat header appears on
  mobile viewports only. On desktop the Drawer is an in-flow panel. Its own
  collapse toggle hides it, and its floating launcher opens it again, so the
  chat header shows no launcher there.
</Callout>

## Add your own "New conversation" button [#add-your-own-new-conversation-button]

The Drawer has its own "New Conversation" row. Your app can also keep its own
button, for example in a toolbar or a page header. To start a new conversation
from that button, call `startNewThread()` from
[`useCopilotChatConfiguration`](/reference/hooks/useCopilotChatConfiguration).
This is the same function the Drawer calls for its own row.

```tsx title="app/page.tsx"
import {
  CopilotKitProvider,
  CopilotChatConfigurationProvider,
  CopilotChat,
  CopilotThreadsDrawer,
  useCopilotChatConfiguration,
} from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

function NewConversationButton() {
  const configuration = useCopilotChatConfiguration(); // [!code highlight]

  return (
    <button
      type="button"
      onClick={() => configuration?.startNewThread()} // [!code highlight]
    >
      New conversation
    </button>
  );
}

export default function Page() {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <CopilotChatConfigurationProvider>
        <div style={{ display: "flex", height: "100dvh" }}>
          <CopilotThreadsDrawer />
          <main style={{ flex: 1, display: "flex", flexDirection: "column" }}>
            <header>
              <NewConversationButton />
            </header>
            <CopilotChat />
          </main>
        </div>
      </CopilotChatConfigurationProvider>
    </CopilotKitProvider>
  );
}
```

How it works:

- Put the button inside the same `<CopilotChatConfigurationProvider>` as the
  Drawer and the chat. Outside a provider, `useCopilotChatConfiguration()`
  returns `null` and the button does nothing.
- `startNewThread()` gives the chat a new thread id and shows the welcome
  screen. The Drawer reads the active thread from the same configuration, so
  no row stays selected.
- The new thread appears in the Drawer list after its first run. An empty
  thread does not get a row.
- If you set the `threadId` prop on `<CopilotChatConfigurationProvider>`, your
  app controls the thread. Then `startNewThread()` and the Drawer's own row
  selection do nothing and log a warning. To control the thread:

  1. Keep the thread id in your own state.
  2. Pass it as `threadId` to `<CopilotChatConfigurationProvider>`.
  3. Pass `onThreadSelect` and `onNewThread` to the Drawer.
  4. Call the same function as `onNewThread` from your button.

  ```tsx
  function ControlledChat() {
    const [threadId, setThreadId] = useState(() => crypto.randomUUID());
    const startNew = () => setThreadId(crypto.randomUUID());

    return (
      <CopilotChatConfigurationProvider threadId={threadId}>
        <CopilotThreadsDrawer
          onThreadSelect={(id) => setThreadId(id)}
          onNewThread={startNew}
        />
        <button type="button" onClick={startNew}>
          New conversation
        </button>
        <CopilotChat />
      </CopilotChatConfigurationProvider>
    );
  }
  ```

To show only your button, hide the Drawer's own new-conversation controls with
their CSS parts. `new-thread-button` is the row in the open Drawer.
`launcher-new-thread` is the (+) button in the closed or collapsed launcher.

```css
copilotkit-threads-drawer::part(new-thread-button),
copilotkit-threads-drawer::part(launcher-new-thread) {
  display: none;
}
```

## Which agent's threads the drawer shows [#which-agents-threads-the-drawer-shows]

The drawer lists the threads of **one** agent. It takes the first agent ID it
finds, in this order:

1. The drawer's own `agentId` prop.
2. The `agentId` of the nearest `<CopilotChatConfigurationProvider>`.
   `<CopilotKit>` renders one of these around your app with its `agent` prop,
   so under `<CopilotKit agent="...">` the drawer stops here. Without `agent`,
   it resolves to `"default"`.
3. The `agentId` on `<CopilotKitProvider>`.
4. `"default"`.

Most framework quickstarts use `<CopilotKit agent="...">`. The built-in agent
and LangGraph quickstarts use `<CopilotKitProvider agentId="...">`. The drawer
finds the agent under either one.

If your runtime registers several agents, the drawer shows only the threads of
the agent it resolved. To list another agent's threads, pass that agent's ID:

```tsx
<CopilotThreadsDrawer agentId="research_agent" />
```

`<CopilotChat>` resolves its agent in the same order. To move the drawer and
the chat to another agent together, set `agentId` once on the shared
`<CopilotChatConfigurationProvider>` instead.

## Configuring the drawer [#configuring-the-drawer]

`<CopilotThreadsDrawer>` works with zero props. The optional ones:

| Prop | Description |
|------|-------------|
| `agentId` | Agent whose threads to list. Defaults to the chat configuration's agent, then `agentId` on `<CopilotKitProvider>`, then `"default"`. See [Which agent's threads the drawer shows](#which-agents-threads-the-drawer-shows). |
| `label` | Accessible name for the drawer region and thread listbox. Defaults to `"Threads"`. The header shows no title. |
| `recentLabel` | Section heading shown above the thread list. Defaults to `"Recent Conversations"`. |
| `onThreadSelect` | Escape hatch to take over thread selection yourself. |
| `onNewThread` | Escape hatch to handle the "New Conversation" row yourself. |
| `renderRow` | Render custom content per row (keeps the row chrome around it). |
| `limit` | Page size for pagination. Shows a "Load more" control while more threads remain. Omit to load all at once. |

See the [Threads Drawer reference](/reference/components/CopilotThreadsDrawer) for the full prop and type list.

## Customization [#customization]

The drawer renders in a shadow root with self-contained, theme-inheriting
styles, so it looks correct in any app (including dark mode) with no config.
Three bounded escape hatches pierce the boundary:

- **Slots**: project children with a `slot` attribute (`header`, `empty`, `footer`, `memories`, `launcher-icon`):

  ```tsx
  <CopilotThreadsDrawer>
    <span slot="header">My conversations</span>
  </CopilotThreadsDrawer>
  ```

- **Per-row content**: the `renderRow` prop projects custom content into each row while the element keeps selection, archived styling, and the per-row kebab menu (Archive/Delete).
- **CSS parts + variable tokens**: restyle structural `::part()`s or override `--cpk-drawer-*` tokens. The full list is in the [reference](/reference/components/CopilotThreadsDrawer#customization).

## Intelligence access [#intelligence-access]

Threads require CopilotKit Intelligence. The drawer resolves its entitlement
through the Runtime, so the credential is server-side configuration rather than a
prop on the provider. Which credential you set depends on how you deploy.

**Cloud-hosted Intelligence.** The project-scoped `CPK_INTELLIGENCE_API_KEY` is the
credential, and the Runtime resolves the drawer's entitlement from your
organization's subscription. Cloud-hosted setup does not issue
`COPILOTKIT_LICENSE_TOKEN`. That token is only for offline or self-hosted
licensing and does not replace the cloud-hosted project API key. If the CLI created
your project, the key is already in `.env` and the drawer needs nothing further.

**Self-hosted and open source.** Give the Runtime a license token, either as the
`licenseToken` option or as the `COPILOTKIT_LICENSE_TOKEN` environment variable.
The option wins when you set both. Without a token the drawer shows a locked
view with an Upgrade link in place of the list, and it issues no thread
requests.

The locked view appears whenever the Runtime reports no active entitlement: a
self-hosted deployment whose license token is missing or expired, or a cloud-hosted
project whose subscription is inactive.

To compare thread UIs and deployment paths, see the [threads overview](/ag2/AG-UI-Streams).
