CopilotPopup
Floating chat bubble that toggles open an overlay chat window.
"use client";import React from "react";import { CopilotKit } from "@copilotkit/react-core";import { CopilotPopup, useConfigureSuggestions,} from "@copilotkit/react-core/v2";export default function PrebuiltPopupDemo() { return ( <CopilotKit runtimeUrl="/api/copilotkit" agent="prebuilt-popup"> <MainContent /> <CopilotPopup agentId="prebuilt-popup" defaultOpen={true} labels={{ chatInputPlaceholder: "Ask the popup anything...", }} /> <Suggestions /> </CopilotKit> );}function MainContent() { return ( <main className="min-h-screen w-full p-12"> <h1 className="text-3xl font-semibold mb-4"> Popup demo — look for the floating launcher </h1> <p className="text-gray-600 max-w-xl"> This page showcases the pre-built <code><CopilotPopup /></code>{" "} component wired to a Mastra-backed agent. A floating launcher bubble sits in the corner, opening an overlay chat window on top of the page content. It starts open by default to make the popup form factor obvious. </p> </main> );}function Suggestions() { useConfigureSuggestions({ suggestions: [{ title: "Say hi", message: "Say hi from the popup!" }], available: "always", }); return null;}What is this?#
<CopilotPopup> is a prebuilt floating launcher that opens an overlay chat
window on top of your page content. It's the lightest-weight way to add a
copilot to an existing app. Drop it in once and a bubble appears in the
corner ready to chat.
When should I use this?#
Use the popup when you want:
- A minimal-footprint copilot that overlays existing content on demand
- A launcher you can place on top of any page without reflowing the layout
- A quick assistant bubble that users open for short, task-focused chats
If you need chat to live alongside your content rather than on top of it,
use CopilotSidebar. For a fully embedded
chat pane, use <CopilotChat> directly.
Basic setup#
Wrap your app in <CopilotKit> once (the provider wires the runtime,
session, and agent registry) and render <CopilotPopup> as a sibling of
your main content. The example below opens the popup by default and
customizes the input placeholder via labels:
<CopilotKit runtimeUrl="/api/copilotkit" agent="prebuilt-popup"> <MainContent /> <CopilotPopup agentId="prebuilt-popup" defaultOpen={true} labels={{ chatInputPlaceholder: "Ask the popup anything...", }} /> <Suggestions /> </CopilotKit>Configuring the popup#
<CopilotPopup> accepts the same props as <CopilotChat> plus a few of
its own. Commonly used options:
| Prop | Description |
|---|---|
defaultOpen | Whether the popup starts open on first render. |
agentId | Agent slug the popup should talk to (must match an agent configured on the runtime). |
labels | User-facing copy for the header, placeholder, and disclaimer. |
header | Slot for the popup header bar — see the slot system. |
toggleButton | Slot for the floating launcher button. |
Styling#
CopilotPopup participates in the slot system, so every piece of its UI
is customizable, from Tailwind classes on the message view to a full
component swap for the header or toggle button. See
custom look and feel for the full slot
reference.
