# CopilotThreadsDrawer

> Prebuilt threads drawer that lists, switches, and manages threads next to CopilotChat

## Overview [#overview]

`CopilotThreadsDrawer` is a prebuilt thread switcher. Put it and [`CopilotChat`](/reference/components/CopilotChat) inside one `CopilotChatConfigurationProvider`. It lists the threads of the user and lets them switch, start, archive, and delete threads with **no active-thread state to wire up**. (Thread rename is available headlessly via [`useThreads`](/reference/hooks/useThreads), not through the drawer's row menu.) It is a thin React wrapper around the framework-agnostic `<copilotkit-threads-drawer>` shadow-DOM web component, fed by the [`useThreads`](/reference/hooks/useThreads) hook and the surrounding chat configuration.

When `onThreadSelect` / `onNewThread` are omitted, the drawer drives the surrounding chat configuration directly: selecting a row connects the chat to that thread (and replays its history); the "New Conversation" row resets the chat to a fresh welcome screen. Pass the callbacks only to take control of the active thread yourself.

Pair it with the v2 `CopilotChat` or `CopilotSidebar` from `@copilotkit/react-core/v2`. `@copilotkit/react-ui` exports components with those same two names, and those are the [deprecated v1 components](/migrate/v2).

See the [CopilotThreadsDrawer guide](/prebuilt-components/copilot-threads-drawer) for a walkthrough, and [`useThreads`](/reference/hooks/useThreads) for the headless data layer underneath.

## Import [#import]

```tsx
import { CopilotThreadsDrawer } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";
```

## Props [#props]

<PropertyReference name="agentId" type="string">
  The agent whose threads to list and manage. The drawer lists one agent's
  threads. When omitted, it uses the agent of the nearest
  `CopilotChatConfigurationProvider`, then `agentId` on `CopilotKitProvider`,
  then `"default"`. `CopilotKit` sets the chat configuration from its `agent`
  prop (`"default"` when `agent` is omitted). Pass it
  when your runtime registers several agents and the drawer should list a
  different one.
</PropertyReference>

<PropertyReference name="onThreadSelect" type="(threadId: string) => void">
  Optional escape hatch called when the user picks a thread row. When omitted,
  the drawer drives the surrounding chat configuration directly
  (`setActiveThreadId`), so a drawer that shares a
  `CopilotChatConfigurationProvider` with the chat switches the rendered thread
  with no host wiring. Provide this only to take control of the active
  thread yourself.
</PropertyReference>

<PropertyReference name="onNewThread" type="() => void">
  Optional escape hatch called when the user starts a new thread (the
  "New Conversation" row). The wrapper always resets the core thread store to a
  fresh, non-explicit thread; when this is omitted it also resets the surrounding
  chat configuration so the welcome screen shows with no host wiring.
</PropertyReference>

<PropertyReference name="renderRow" type="(thread: Thread) => React.ReactNode">
  Optional per-row content. Rendered as light-DOM children projected into the
  element's `slot="row:{id}"`, so the element keeps the row chrome (selection,
  archived styling, entry animation, actions) around your content. Return
  `null` for a given row to keep the element's default row name.
</PropertyReference>

<PropertyReference name="label" type="string" default="Threads">
  Accessible name for the drawer. Sets the `aria-label` on both the drawer region
  and the thread listbox. The header has no visible title. To add one, project
  content into the `header` slot.
</PropertyReference>

<PropertyReference name="recentLabel" type="string" default="Recent Conversations">
  Text of the section heading shown above the thread list (the `section-heading`
  part), alongside the filter funnel.
</PropertyReference>

<PropertyReference name="limit" type="number">
  Page size for thread pagination. When set, threads load in pages of this size
  and a "Load more" control appears at the bottom of the list while more remain
  (the element emits a `load-more` event the wrapper routes to
  `fetchMoreThreads`). Omit to load the full list at once with no control.
</PropertyReference>

<PropertyReference name="collapsible" type="boolean" default="true">
  Whether the drawer offers a collapse toggle on desktop. When `true` (default),
  a sidebar toggle shows in the header. Collapsing replaces the panel with a
  small floating cluster: a sidebar toggle and a "New Conversation" button. The
  drawer then sets `--cpk-drawer-reserved-width: 0px` on the document root, so a
  host grid that reads this variable can use the column. Set `false` to omit the
  toggle and keep the drawer always expanded.
</PropertyReference>

<PropertyReference name="onCollapseChange" type="(collapsed: boolean) => void">
  Called when the user toggles the desktop collapse state, with the new
  `collapsed` value. Optional: the drawer manages its own collapse state; use
  this only to mirror it into your own layout.
</PropertyReference>

<PropertyReference name="data-testid" type="string" default="copilot-threads-drawer">
  `data-testid` set on the underlying custom element, for tests and for
  targeting from a host page.
</PropertyReference>

## Customization [#customization]

The drawer renders inside a shadow root and ships its own self-contained,
theme-inheriting styles, so it looks correct in any host (including dark mode)
with zero config. Three bounded escape hatches pierce the boundary.

### Slots [#slots]

Project light-DOM children with a `slot` attribute to replace a region:

| Slot | Replaces |
| --- | --- |
| `header` | The drawer header region (renders only when you project content). |
| `empty` | The empty-state body shown when there are no threads. |
| `footer` | A footer region (hidden until you project content). |
| `memories` | An extra region above the footer, hidden until you project content. |
| `launcher-icon` | The icon inside the floating mobile launcher. |
| `row:{id}` | Per-row content. Prefer the `renderRow` prop, which manages this. |

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

### CSS parts [#css-parts]

Style structural elements with `::part()`:

- **Structure**: `root`, `header`, `list`, `footer`
- **Rows**: `row`, `row-active` (the selected row), `row-name`, `row-menu` (kebab), `row-menu-popover`, `row-archive`, `row-unarchive`, `row-delete`
- **New conversation & sections**: `new-thread-button`, `section-heading`
- **Filter**: `filter-toggle`, `filter-indicator`, `filter-active`, `filter-all`, `filters`
- **Collapse, mobile & launcher**: `collapse-toggle` (desktop), `close-toggle` (mobile), `backdrop` (mobile scrim), `launcher`, `launcher-cluster`, `launcher-new-thread`
- **Pagination**: `load-more`, `fetching-more`, `fetch-more-error`, `fetch-more-retry`
- **States & upsell**: `loading`, `empty`, `error`, `retry-button`, `licensed`, `licensed-cta`, `memories`
- **Delete confirm dialog**: `confirm-dialog`, `confirm-cancel`, `confirm-delete`

The Active/All filter lives behind the `filter-toggle` funnel, whose
`filter-indicator` dot shows when a non-default filter is applied. Per-row
Archive/Delete actions live in the `row-menu` kebab and its `row-menu-popover`.
When the list is collapsed on desktop (or closed on mobile), the floating
`launcher-cluster` holds the `launcher` toggle and the `launcher-new-thread`
button.

### CSS variable tokens [#css-variable-tokens]

Tokens override the bundled defaults. Color tokens fall back to the host theme
variable in the Fallback column, so the drawer follows light and dark themes
automatically.

| Group             | Token                       | Fallback             | Sets                                                     |
| ----------------- | --------------------------- | -------------------- | -------------------------------------------------------- |
| Colors            | `--cpk-drawer-bg`           | `--background`       | Background of the drawer panel.                          |
| Colors            | `--cpk-drawer-fg`           | `--foreground`       | Text color of the drawer.                                |
| Colors            | `--cpk-drawer-border`       | `--border`           | Borders of the panel, the launcher cluster, and menus.   |
| Colors            | `--cpk-drawer-surface`      | `--card`             | Background of the launcher cluster and the menus.        |
| Colors            | `--cpk-drawer-surface-fg`   | `--card-foreground`  | Text on the launcher cluster and the menus.              |
| Colors            | `--cpk-drawer-muted`        | `--muted`            | Hover and pressed background of the icon buttons.        |
| Colors            | `--cpk-drawer-muted-fg`     | `--muted-foreground` | Section headings, archived rows, and icon buttons.       |
| Colors            | `--cpk-drawer-accent`       | `--accent`           | Background of the active row.                            |
| Colors            | `--cpk-drawer-accent-fg`    | `--accent-foreground`| Text of the active row.                                  |
| Colors            | `--cpk-drawer-primary`      | `--primary`          | Background of primary buttons.                           |
| Colors            | `--cpk-drawer-primary-fg`   | `--primary-foreground`| Text of primary buttons.                                |
| Colors            | `--cpk-drawer-danger`       | `--destructive`      | The delete action and error text.                        |
| Colors            | `--cpk-drawer-indicator`    | `#5b94e4`            | The dot that shows a filter is applied.                  |
| Colors            | `--cpk-drawer-ring`         | `--ring`             | Focus ring color. The current styles do not read it.     |
| Shape             | `--cpk-drawer-radius`       | `--radius`           | Corner radius, capped at `4px`.                          |
| Shape             | `--cpk-drawer-width`        | `320px`              | Width of the drawer.                                     |
| Type              | `--cpk-drawer-font-family`  | `ui-sans-serif`      | Font family.                                             |
| Type              | `--cpk-drawer-font-size`    | `14px`               | Font size.                                               |
| Type              | `--cpk-drawer-line-height`  | `1.4`                | Line height.                                             |
| Launcher position | `--cpk-drawer-launcher-top` | `24px`               | Distance of the launcher cluster from the top.           |
| Launcher position | `--cpk-drawer-launcher-left`| `24px`               | Distance of the launcher cluster from the left.          |

## Usage [#usage]

### Basic usage [#basic-usage]

Wrap the drawer and `CopilotChat` in a shared `CopilotChatConfigurationProvider`
so they operate on the **same** chat configuration. That shared config is how
selecting a thread (or "New Conversation") drives the chat. Without a shared
provider the drawer sits beside the chat's own scoped configuration and can't
switch its thread.

```tsx
import {
  CopilotThreadsDrawer,
  CopilotChat,
  CopilotChatConfigurationProvider,
} from "@copilotkit/react-core/v2";

function App() {
  return (
    <CopilotChatConfigurationProvider>
      <div style={{ display: "flex", height: "100%" }}>
        <CopilotThreadsDrawer />
        <CopilotChat />
      </div>
    </CopilotChatConfigurationProvider>
  );
}
```

### Custom row content + label [#custom-row-content--label]

```tsx
function App() {
  return (
    <CopilotThreadsDrawer
      label="History"
      renderRow={(thread) => <em>{thread.name ?? "New conversation"}</em>}
    />
  );
}
```

## Behavior [#behavior]

- **Self-connecting**: without `onThreadSelect`/`onNewThread`, the drawer drives the chat configuration. Select connects + replays; the "New Conversation" row shows the welcome screen.
- **Collapsible sidebar**: on larger screens the drawer is an expanded sidebar by default with a collapse toggle (sidebar glyph) in the header. Collapsing replaces the panel with a small floating cluster: a sidebar toggle to expand plus a "New Conversation" button. Collapsing also lets a host grid reclaim the column (via `--cpk-drawer-reserved-width`). Set `collapsible={false}` to omit the toggle. "New Conversation" is its own row below the header; project `slot="header"` content to add your own chrome beside the toggle.
- **Row actions**: per-row **Archive/Delete** live behind a per-row kebab (⋮) menu (`row-menu`); delete asks for confirmation.
- **Optimistic mutations**: archive/unarchive/rename/delete are optimistic in the core thread store; delete rolls back if the server rejects.
- **Deleting the active thread** resets to a fresh thread; **archiving** the active thread keeps you viewing it. Archived threads render italic/muted inline in the "All" view.
- **Filter**: an Active/All filter lives behind a **funnel** icon popover under the "Recent Conversations" heading; a small indicator dot appears on the funnel when a non-default filter is applied. Toggling the filter refetches server-side.
- **Mobile**: below 768px the drawer is an off-canvas modal. Closed, it shows the same floating cluster (a launcher to open it + a "New Conversation" button); open, it slides in and is dismissed by tapping the backdrop or pressing Escape. The launcher icon (`launcher-icon` slot) and position (`--cpk-drawer-launcher-*`) are customizable.
- **Intelligence access**: threads require CopilotKit Intelligence. If the runtime reports that Threads are unavailable, the drawer shows a locked view in place of the list. Cloud-hosted projects use `CPK_INTELLIGENCE_API_KEY` on the server. A licensed self-hosted deployment uses `COPILOTKIT_LICENSE_TOKEN` on the server.
