# CopilotPopup

> Popup variant of CopilotChat that renders in a floating panel with a toggle button

## Overview [#overview]

`CopilotPopup` renders a floating chat popup with a toggle button. It wraps [`CopilotChat`](/reference/components/CopilotChat) and provides popup-specific layout, sizing, and open/close behavior. The popup includes a header with a title and close button, and can be dismissed by clicking outside.

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

For a walkthrough, see [Popup](/prebuilt-components/popup).

## Import [#import]

```tsx
import { CopilotPopup } 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 popup 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 popup is open when the component first mounts. After that the
  popup 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 popup is
  open: the popup 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 popup asks to open or close (the
  toggle button, click-outside, Escape, 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 popup panel. Accepts a number (pixels) or a CSS string (e.g.
  `"400px"`, `"30vw"`).
</PropertyReference>

<PropertyReference name="height" type="number | string">
  Height of the popup panel. Accepts a number (pixels) or a CSS string (e.g.
  `"600px"`, `"80vh"`).
</PropertyReference>

<PropertyReference name="clickOutsideToClose" type="boolean" default="true">
  Whether clicking outside the popup panel closes it.
</PropertyReference>

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

`CopilotPopup` accepts all props from [`CopilotChatProps`](/reference/components/CopilotChat) **except** `chatView`, which is set internally to `CopilotPopupView`. 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 (
    <CopilotPopup
      agentId="my-agent"
      labels={{ modalHeaderTitle: "Assistant" }}
    />
  );
}
```

### Custom Size and Default Open [#custom-size-and-default-open]

```tsx
function App() {
  return (
    <CopilotPopup
      agentId="my-agent"
      defaultOpen={true}
      width={450}
      height="80vh"
      clickOutsideToClose={false}
    />
  );
}
```

### Custom Header [#custom-header]

```tsx
function App() {
  return <CopilotPopup agentId="my-agent" header="bg-blue-600 text-white" />;
}
```

## Behavior [#behavior]

- **Toggle button**: Renders a floating toggle button (typically in the bottom-right corner) that opens and closes the popup. 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, clicking outside). Pass `open` and `onOpenChange` to own the state yourself, and to open or close the popup from your own UI.
- **Click outside**: When `clickOutsideToClose` is `true` (the default), clicking anywhere outside the popup panel closes it.
- **Layout**: The popup uses `CopilotPopupView` internally. `CopilotPopupView` builds on [`CopilotChatView`](/reference/components/CopilotChatView) and provides a popup-specific welcome screen layout with the welcome message centered vertically and suggestions just above the input.
- **Agent connection**: All agent wiring (messages, running state, suggestions) is handled by the parent `CopilotChat` logic.
