---
title: "CopilotPopup"
description: "The CopilotPopup component, providing a popup interface for interacting with your copilot."
---

{
 /*
  * 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/Popup.tsx
  */
}

<Callout type="warning">
  `CopilotPopup` is still supported, but we recommend migrating to [`CopilotPopup`](/reference/v2/components/CopilotPopup) from the v2 API.
</Callout>

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

A chatbot popup component for the CopilotKit framework. The component allows for a high degree
of customization through various props and custom CSS.

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

## 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

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

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

### With Observability Hooks

To monitor user interactions, provide the `observabilityHooks` prop.
Note: This requires a `publicApiKey` in the `<CopilotKit>` provider.

```tsx
<CopilotKit publicApiKey="YOUR_PUBLIC_API_KEY">
  <CopilotPopup
    observabilityHooks={{
      onChatExpanded: () => {
        console.log("Popup opened");
      },
      onChatMinimized: () => {
        console.log("Popup closed");
      },
    }}
  />
</CopilotKit>
```

### 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/slots) guide.

## 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. These instructions can include specific directions,
  preferences, or criteria that the model should consider when generating
  its output, thereby tailoring the conversation more precisely to the
  user's needs or the application's requirements.
</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
    - Access via `useCopilotChat` hook

  `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) => void"  >
A callback function for thumbs up feedback
</PropertyReference>

<PropertyReference name="onThumbsDown" type="(message: Message) => void"  >
A callback function for thumbs down feedback
</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="imageUploadsEnabled" type="boolean"  >
Enable image upload button (image inputs only supported on some models)
</PropertyReference>

<PropertyReference name="inputFileAccept" type="string"  >
The 'accept' attribute for the file input used for image uploads.
  Defaults to "image".
</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="ImageRenderer" type="React.ComponentType<ImageRendererProps>"  >
A custom image rendering 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"  >

</PropertyReference>

<PropertyReference name="observabilityHooks" type="CopilotObservabilityHooks"  >
Event hooks for CopilotKit chat events.
  These hooks only work when publicApiKey is provided.
</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 comprehensive 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>
