CopilotChat

"use client";import React, { useState } from "react";import {  useFrontendTool,  useRenderTool,  useAgentContext,  useConfigureSuggestions,  CopilotChat,} from "@copilotkit/react-core/v2";import { CopilotKit } from "@copilotkit/react-core";import { z } from "zod";export default function AgenticChatDemo() {  return (    <CopilotKit runtimeUrl="/api/copilotkit" agent="agentic_chat">      <Chat />    </CopilotKit>  );}function Chat() {  const [background, setBackground] = useState<string>(    "var(--copilot-kit-background-color)",  );  useAgentContext({    description: "Name of the user",    value: "Bob",  });  useFrontendTool({    name: "change_background",    description:      "Change the background color of the chat. Can be anything that the CSS background attribute accepts. Regular colors, linear or radial gradients etc.",    parameters: z.object({      background: z        .string()        .describe("The background. Prefer gradients. Only use when asked."),    }),    handler: async ({ background }: { background: string }) => {      setBackground(background);      return {        status: "success",        message: `Background changed to ${background}`,      };    },  });  useRenderTool({    name: "get_weather",    parameters: z.object({      location: z.string(),    }),    render: ({ args, result, status }: any) => {      if (status !== "complete") {        return <div data-testid="weather-info-loading">Loading weather...</div>;      }      return (        <div data-testid="weather-info">          <strong>Weather in {result?.city || args.location}</strong>          <div>Temperature: {result?.temperature}&deg;C</div>          <div>Humidity: {result?.humidity}%</div>          <div>Wind Speed: {result?.windSpeed ?? result?.wind_speed} mph</div>          <div>Conditions: {result?.conditions}</div>        </div>      );    },  });  useConfigureSuggestions({    suggestions: [      {        title: "Change background",        message: "Change the background to something new.",      },      {        title: "Generate sonnet",        message: "Write a short sonnet about AI.",      },    ],    available: "always",  });  return (    <div      className="flex justify-center items-center h-screen w-full"      data-testid="background-container"      style={{ background }}    >      <div className="h-full w-full max-w-4xl">        <CopilotChat agentId="agentic_chat" className="h-full rounded-2xl" />      </div>    </div>  );}

What is this?#

<CopilotChat> is the base prebuilt chat surface. Drop it in wherever you want the chat to render and size it to fit your layout. <CopilotSidebar> and <CopilotPopup> are both thin wrappers over the same primitives; if you need a dedicated chat page or an inline pane alongside other content, this is the component you want.

When should I use this?#

Use <CopilotChat> when you want:

A full-bleed chat that fills its container
An inline chat pane as part of a larger page
A dedicated /chat route
Maximum layout freedom (no docked chrome or launcher)

For a collapsible docked chat, use CopilotSidebar. For a floating bubble that overlays content, use CopilotPopup.

Basic setup#

Wrap your app in <CopilotKit> once (the provider wires the runtime, session, and agent registry) and render <CopilotChat> inside the layout of your choosing:

page.tsx

    <CopilotKit runtimeUrl="/api/copilotkit" agent="agentic_chat">      <Chat />    </CopilotKit>

Code example#

A self-contained component that renders the chat and wires in starter suggestions:

chat-component.snippet.tsx

export function Chat() {  useConfigureSuggestions({    suggestions: [      { title: "Write a sonnet", message: "Write a short sonnet about AI." },    ],    available: "always",  });  return <CopilotChat agentId="agentic_chat" className="h-full rounded-2xl" />;}

Common props#

<CopilotChat> is the root primitive. <CopilotSidebar> and <CopilotPopup> accept the same slots and labels, plus a few wrapper-specific props.

Prop	Description
`agentId`	Agent slug the chat should talk to (must match an agent configured on the runtime).
`labels`	User-facing copy — header title, placeholder, welcome, disclaimer.
`messageView`	Slot for the message list — see slots.
`input`	Slot for the composer area (text area, send button, disclaimer).
`scrollView`	Slot for the scroll container (e.g. custom feather/gradient).
`suggestionView`	Slot for the suggestion pills shown below messages.
`welcomeScreen`	Slot for the empty-state. Pass `false` to disable.

Styling#

<CopilotChat> is fully themable:

CSS variables / class overrides — see CSS customization
Slots (subcomponents) — see slots
Fully headless — see headless UI