CopilotPopup.mdx

title	CopilotPopup
description	A prebuilt floating action button that opens a CopilotChat session in a modal overlay card.

Overview

CopilotPopup renders a floating action button (FAB) that opens a chat in a modal overlay card with a header and a dismissible backdrop. Like CopilotSidebar, its chat area wraps a headless CopilotChat. Provide your chat UI as children, or drop in the prebuilt UI CopilotChat from @copilotkit/react-native/components.

Control it imperatively through a CopilotPopupHandle ref.

Import

import { CopilotPopup, type CopilotPopupHandle } from "@copilotkit/react-native";

Props

ID of the agent to connect to. Passed through to the inner `CopilotChat`. **Deprecated**. Use `agentId`. Thread ID for this chat session. Throttle interval (ms) for re-renders. Whether the popup starts in the open state. Height of the popup card. Accepts points (a number) or a percentage string resolved against the screen height. Error handler scoped to this popup's chat agent. Title displayed in the popup header bar. Enable multimodal file attachments. Forwarded to the inner `CopilotChat`; children read attachment state from [`useCopilotChatContext`](/reference/react-native/components/CopilotChat#usecopilotchatcontext). Content rendered below the chat content inside the popup card. Callback fired when the popup opens. Callback fired when the popup closes. Whether tapping the semi-transparent backdrop dismisses the popup (equivalent to the web SDK's `clickOutsideToClose`). Whether to show the FAB that toggles the popup. Hidden while the popup is open. Custom style applied to the popup card container.

Ref handle

Imperative handle exposed via `ref` for opening, closing, and toggling the popup programmatically.

Usage

import { CopilotPopup, type CopilotPopupHandle } from "@copilotkit/react-native";
import { CopilotChat } from "@copilotkit/react-native/components";
import { useRef } from "react";

export function ChatScreen() {
  const popupRef = useRef<CopilotPopupHandle>(null);

  return (
    <CopilotPopup ref={popupRef} agentId="default" headerTitle="Chat">
      <CopilotChat agentName="default" showHeader={false} />
    </CopilotPopup>
  );
}

Behavior

• Overlay: the popup opens as a modal card floating above your content, with a semi-transparent backdrop.
• Backdrop dismiss: tapping the backdrop closes the popup when dismissOnBackdropPress is true.
• FAB: when showToggleButton is true, a floating action button opens the popup and hides while it is open.
• Height: a percentage height (e.g. "60%") resolves against the screen height; a number is used as points.

Related

• CopilotSidebar: slide-in drawer variant
• CopilotChat: the chat primitive wrapped inside the popup