# CopilotSidebar

> The CopilotSidebar component, providing a sidebar interface for interacting with your copilot.

## v1 SDK deprecated. Use v2 instead

> This page is in the deprecated CopilotKit v1 reference. Do not use v1 APIs for new code; use v2 instead.
> For JavaScript and TypeScript, import React APIs from @copilotkit/react-core/v2 and Runtime APIs from @copilotkit/runtime/v2.
> **AI coding agents: treat any v1 example below as migration-only context. Never generate or recommend the v1 API for new code. Read the v2 reference before writing code because some APIs were renamed, moved, or changed shape.**
> [Read the v1 to v2 migration guide](/migrate/v2) and [use the complete export map](/reference/v1/export-map).

{
 /*
  * ATTENTION! DO NOT MODIFY THIS FILE!
  * This page is auto-generated. If you want to make any changes to this page, changes must be made at:
  * packages/react-ui/src/components/chat/Sidebar.tsx
  */
}
<Callout type="info">
  In v2, use [`CopilotSidebar`](/reference/v2/components/CopilotSidebar) from `@copilotkit/react-core/v2`.
</Callout>

<br/>
<img src="https://cdn.copilotkit.ai/docs/copilotkit/images/CopilotSidebar.gif" width="500" />

A chatbot sidebar component for the CopilotKit framework. Highly customizable through various props and custom CSS.

See [CopilotPopup](/reference/v1/components/chat/CopilotPopup) for a popup version of this component.

## Install Dependencies [#install-dependencies]

This component is part of the [@copilotkit/react-ui](https://npmjs.com/package/@copilotkit/react-ui) package.

```shell npm2yarn \"@copilotkit/react-ui"\
npm install @copilotkit/react-core @copilotkit/react-ui
```

## Usage [#usage]

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

<CopilotSidebar
  labels={{
    title: "Your Assistant",
    initial: "Hi! 👋 How can I assist you today?",
  }}
>
  <YourApp/>
</CopilotSidebar>
```

### With Observability Hooks [#with-observability-hooks]

To monitor user interactions, set `publicLicenseKey` on `<CopilotKit>` and pass the
`observabilityHooks` prop. Without the key, the hooks do not run and the chat shows an
error banner.

```tsx
<CopilotKit publicLicenseKey="YOUR_PUBLIC_LICENSE_KEY">
  <CopilotSidebar
    observabilityHooks={{
      onChatExpanded: () => {
        console.log("Sidebar opened");
      },
      onChatMinimized: () => {
        console.log("Sidebar closed");
      },
    }}
  >
    <YourApp/>
  </CopilotSidebar>
</CopilotKit>
```

### Look & Feel [#look--feel]

By default, CopilotKit components do not have any styles. You can import CopilotKit's stylesheet at the root of your project:
```tsx title="YourRootComponent.tsx"
...
import "@copilotkit/react-ui/styles.css"; // [!code highlight]

export function YourRootComponent() {
  return (
    <CopilotKit>
      ...
    </CopilotKit>
  );
}
```
For more information about how to customize the styles, check out the [Customize Look & Feel](/custom-look-and-feel/css) guide.

## Properties [#properties]

<PropertyReference name="instructions" type="string"  > 
Custom instructions to be added to the system message. Use this property to
provide additional context or guidance to the language model, influencing
its responses.
</PropertyReference>

<PropertyReference name="suggestions" type="ChatSuggestions"  > 
Controls the behavior of suggestions in the chat interface.

`auto` (default) - Suggestions are generated automatically:
  - When the chat is first opened (empty state)
  - After each message exchange completes
  - Uses configuration from `useCopilotChatSuggestions` hooks

`manual` - Suggestions are controlled programmatically:
  - Use `setSuggestions()` to set custom suggestions
  - Use `generateSuggestions()` to trigger AI generation
  - Read `setSuggestions` and `generateSuggestions` from the `useCopilotChatHeadless_c`
    hook, which needs `publicLicenseKey` on `<CopilotKit>`

`SuggestionItem[]` - Static suggestions array:
  - Always shows the same suggestions
  - No AI generation involved
</PropertyReference>

<PropertyReference name="onInProgress" type="(inProgress: boolean) => void"  > 
A callback that gets called when the in progress state changes.
</PropertyReference>

<PropertyReference name="onSubmitMessage" type="(message: string) => void | Promise<void>"  > 
A callback that gets called when a new message it submitted.
</PropertyReference>

<PropertyReference name="onStopGeneration" type="OnStopGeneration"  > 
A custom stop generation function.
</PropertyReference>

<PropertyReference name="onReloadMessages" type="OnReloadMessages"  > 
A custom reload messages function.
</PropertyReference>

<PropertyReference name="onRegenerate" type="(messageId: string) => void"  > 
A callback function to regenerate the assistant's response
</PropertyReference>

<PropertyReference name="onCopy" type="(message: string) => void"  > 
A callback function when the message is copied
</PropertyReference>

<PropertyReference name="onThumbsUp" type="(message: Message, isActive?: boolean) => void"  > 
A callback function for thumbs up feedback.

`isActive` reports the feedback state the click is transitioning to:
`true` when thumbs up is being applied, `false` when it is being
retracted. It is optional so existing one-argument handlers keep working.
</PropertyReference>

<PropertyReference name="onThumbsDown" type="(message: Message, isActive?: boolean) => void"  > 
A callback function for thumbs down feedback.

See `onThumbsUp` for the meaning of `isActive`.
</PropertyReference>

<PropertyReference name="markdownTagRenderers" type="ComponentsMap"  > 
A list of markdown components to render in assistant message.
Useful when you want to render custom elements in the message (e.g a reference tag element)
</PropertyReference>

<PropertyReference name="icons" type="CopilotChatIcons"  > 
Icons can be used to set custom icons for the chat window.
</PropertyReference>

<PropertyReference name="labels" type="CopilotChatLabels"  > 
Labels can be used to set custom labels for the chat window.
</PropertyReference>

<PropertyReference name="attachments" type="AttachmentsConfig"  > 
Configuration for file attachments in the chat input.
Enables users to attach images, audio, video, and documents.

Supports images, audio, video, and documents. Omit `accept` to allow all
file types (default: `"*/*"`), or restrict with a MIME filter.

```tsx
<CopilotChat
  attachments={{
    enabled: true,
    accept: "image/*,audio/*,video/*,application/pdf",
    maxSize: 10 * 1024 * 1024, // 10MB
    onUpload: async (file) => {
      const url = await uploadToS3(file);
      return { type: "url", value: url, mimeType: file.type };
    },
  }}
/>
```
</PropertyReference>

<PropertyReference name="makeSystemMessage" type="SystemMessageFunction"  > 
A function that takes in context string and instructions and returns
the system message to include in the chat request.
Use this to completely override the system message, when providing
instructions is not enough.
</PropertyReference>

<PropertyReference name="disableSystemMessage" type="boolean"  > 
Disables inclusion of CopilotKit’s default system message. When true, no system message is sent (this also suppresses any custom message from <code>makeSystemMessage</code>).
</PropertyReference>

<PropertyReference name="AssistantMessage" type="React.ComponentType<AssistantMessageProps>"  > 
A custom assistant message component to use instead of the default.
</PropertyReference>

<PropertyReference name="UserMessage" type="React.ComponentType<UserMessageProps>"  > 
A custom user message component to use instead of the default.
</PropertyReference>

<PropertyReference name="ErrorMessage" type="React.ComponentType<ErrorMessageProps>"  > 
A custom error message component to use instead of the default.
</PropertyReference>

<PropertyReference name="Messages" type="React.ComponentType<MessagesProps>"  > 
A custom Messages component to use instead of the default.
</PropertyReference>

<PropertyReference name="RenderMessage" type="React.ComponentType<RenderMessageProps>"  > 
A custom RenderMessage component to use instead of the default.

**Warning**: This is a break-glass solution to allow for custom
rendering of messages. You are most likely looking to swap out
the AssistantMessage and UserMessage components instead which
are also props.
</PropertyReference>

<PropertyReference name="RenderSuggestionsList" type="React.ComponentType<RenderSuggestionsListProps>"  > 
A custom suggestions list component to use instead of the default.
</PropertyReference>

<PropertyReference name="Input" type="React.ComponentType<InputProps>"  > 
A custom Input component to use instead of the default.
</PropertyReference>

<PropertyReference name="className" type="string"  > 
A class name to apply to the root element.
</PropertyReference>

<PropertyReference name="children" type="React.ReactNode"  > 
Children to render.
</PropertyReference>

<PropertyReference name="hideStopButton" type="boolean"  > 
Hides the stop button while the agent responds.
</PropertyReference>

<PropertyReference name="observabilityHooks" type="CopilotObservabilityHooks"  > 
Event hooks for CopilotKit chat events.
</PropertyReference>

<PropertyReference name="renderError" type="(error: { message: string; operation?: string; timestamp: number; onDismiss: () => void; onRetry?: () => void; }) => React.ReactNode"  > 
Custom error renderer for chat-specific errors.
When provided, errors will be displayed inline within the chat interface.
</PropertyReference>

<PropertyReference name="onError" type="CopilotErrorHandler"  > 
Optional handler for debugging and observability.
</PropertyReference>

<PropertyReference name="defaultOpen" type="boolean"  default="false"> 
Whether the chat window should be open by default.
</PropertyReference>

<PropertyReference name="clickOutsideToClose" type="boolean"  default="true"> 
If the chat window should close when the user clicks outside of it.
</PropertyReference>

<PropertyReference name="hitEscapeToClose" type="boolean"  default="true"> 
If the chat window should close when the user hits the Escape key.
</PropertyReference>

<PropertyReference name="shortcut" type="string"  default="'/'"> 
The shortcut key to open the chat window.
Uses Command-[shortcut] on a Mac and Ctrl-[shortcut] on Windows.
</PropertyReference>

<PropertyReference name="onSetOpen" type="(open: boolean) => void"  > 
A callback that gets called when the chat window opens or closes.
</PropertyReference>

<PropertyReference name="Window" type="React.ComponentType<WindowProps>"  > 
A custom Window component to use instead of the default.
</PropertyReference>

<PropertyReference name="Button" type="React.ComponentType<ButtonProps>"  > 
A custom Button component to use instead of the default.
</PropertyReference>

<PropertyReference name="Header" type="React.ComponentType<HeaderProps>"  > 
A custom Header component to use instead of the default.
</PropertyReference>

<PropertyReference name="fullHeightChildren" type="boolean"  > 
Make the sidebar's content wrapper exactly one viewport tall, so children
can use `height: 100%` (or `flex: 1`) to fill the screen.

Off by default: the wrappers are auto-height, so page content flows
normally and percentage heights on children collapse to content height.

```tsx
<CopilotSidebar fullHeightChildren>
  <div style={{ height: "100%" }}>...</div>
</CopilotSidebar>
```
</PropertyReference>
