# CopilotSidebar

> Sidebar variant of CopilotChat that renders in a fixed side panel

## Overview [#overview]

`CopilotSidebar` renders a fixed sidebar panel for chat interaction. It wraps [`CopilotChat`](/reference/components/CopilotChat) and provides sidebar-specific layout and open/close behavior. The sidebar includes a header with a title and close button, and can be toggled via a floating button.

See [`CopilotPopup`](/reference/components/CopilotPopup) for a popup variant of this component.

For a walkthrough, see [Sidebar](/prebuilt-components/sidebar).

## Import [#import]

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

## Props [#props]

### Own Props [#own-props]

<PropertyReference name="header" type="SlotValue<typeof CopilotModalHeader>">
  Slot override for the sidebar header. Accepts a replacement component, a
  `className` string merged into the default, or a partial props object. The
  default header displays a title and a close button.
</PropertyReference>

<PropertyReference name="defaultOpen" type="boolean" default="true">
  Whether the sidebar is open when the component first mounts. After that the
  sidebar owns the state. Use `open` instead to keep control.
</PropertyReference>

<PropertyReference name="open" type="boolean">
  Controlled open state. When supplied, your component owns whether the sidebar
  is open: the sidebar renders this value and never changes it on its own. Pair
  it with `onOpenChange`. When both `open` and `defaultOpen` are passed, `open`
  wins. See [Open, close, and
  feedback](/prebuilt-components/chat-controls).
</PropertyReference>

<PropertyReference name="onOpenChange" type="(open: boolean) => void">
  Called with the requested state whenever the sidebar asks to open or close
  (the toggle button, or the thread drawer on mobile). It reports a request, not
  a change: in controlled mode nothing moves until you update `open`.
</PropertyReference>

<PropertyReference name="width" type="number | string">
  Width of the sidebar panel. Accepts a number (pixels) or a CSS string (e.g.
  `"400px"`, `"30vw"`).
</PropertyReference>

### Inherited CopilotChat Props [#inherited-copilotchat-props]

`CopilotSidebar` accepts all props from [`CopilotChatProps`](/reference/components/CopilotChat) **except** `chatView`, which is set internally to `CopilotSidebarView`. This includes:

<PropertyReference name="agentId" type="string">
  ID of the agent to use. Must match an agent configured in
  `CopilotKit`.
</PropertyReference>

<PropertyReference name="threadId" type="string">
  ID of the conversation thread.
</PropertyReference>

<PropertyReference name="labels" type="Partial<CopilotChatLabels>">
  Partial label overrides for all text strings rendered inside the chat.
</PropertyReference>

<PropertyReference name="autoScroll" type='"pin-to-bottom" | "pin-to-send" | "none" | boolean' default="true">
  How the chat scrolls when messages arrive:

- `"pin-to-bottom"` or `true`: keep the latest message in view while the user is at the bottom.
- `"pin-to-send"`: when the user sends a message, scroll that message to the top of the view and keep it there while the reply streams.
- `"none"` or `false`: do not scroll automatically.

</PropertyReference>

<PropertyReference
  name="welcomeScreen"
  type="SlotValue<React.FC<WelcomeScreenProps>> | boolean"
>
  Controls the welcome screen shown when no messages exist.
</PropertyReference>

The `CopilotChatView` slots `messageView`, `input`, `scrollView`, and `suggestionView` are also accepted and forwarded. To pass props to the input, use the `input` slot, for example `input={{ autoFocus: true }}`. The `disclaimer` prop is deprecated. Use `input={{ disclaimer: MyDisclaimer }}` instead.

## Slot System [#slot-system]

All slot props follow the same override pattern used across CopilotKit v2 components. Each slot accepts one of three value types:

| Value                    | Behavior                                                                            |
| ------------------------ | ----------------------------------------------------------------------------------- |
| **Component**            | Replaces the default component entirely. Receives the same props the default would. |
| **`className` string**   | Merged into the default component's class list via `twMerge`.                       |
| **Partial props object** | Spread into the default component as additional or overriding props.                |

## Usage [#usage]

### Basic Usage [#basic-usage]

```tsx
function App() {
  return (
    <CopilotSidebar
      agentId="my-agent"
      labels={{ modalHeaderTitle: "Assistant" }}
    />
  );
}
```

### Default Open with Custom Width [#default-open-with-custom-width]

```tsx
function App() {
  return <CopilotSidebar agentId="my-agent" defaultOpen={true} width={500} />;
}
```

### Custom Header [#custom-header]

```tsx
function App() {
  return (
    <CopilotSidebar agentId="my-agent" header="bg-indigo-700 text-white" />
  );
}
```

## Behavior [#behavior]

- **Toggle button**: Renders a floating toggle button that opens and closes the sidebar. The button uses `CopilotChatToggleButton` internally.
- **Modal state**: Open/close state is managed via the chat configuration context. The `defaultOpen` prop sets the initial state; after that, state changes come from user interaction (toggle button, close button in the header). Pass `open` and `onOpenChange` to own the state yourself, and to open or close the sidebar from your own UI.
- **Layout**: The sidebar uses `CopilotSidebarView` internally. `CopilotSidebarView` builds on [`CopilotChatView`](/reference/components/CopilotChatView) and provides a sidebar-specific welcome screen layout with the welcome message centered and the suggestions just above the input at the bottom.
- **Fixed positioning**: The sidebar renders as a fixed panel on one side of the viewport. On screens 768 px wide or wider, the open sidebar adds a margin to `document.body` on its side, so your page content moves aside. On narrower screens, it covers the page.
- **Agent connection**: All agent wiring (messages, running state, suggestions) is handled by the parent `CopilotChat` logic.
