Slots

What is this?#

Every CopilotKit chat component is built from composable slots — named sub-components that you can override individually. The slot system gives you three levels of customization without needing to rebuild the entire UI:

1. Tailwind classes — pass a string to add/override CSS classes
2. Props override — pass an object to override specific props on the default component
3. Custom component — pass your own React component to fully replace a slot

Slots are recursive — you can drill into nested sub-components at any depth.

Tailwind Classes#

The simplest way to customize a slot. Pass a Tailwind class string and it will be merged with the default component's classes.

import { CopilotChat } from "@copilotkit/react-core/v2";

export function Chat() {
  return (
    <CopilotChat
      messageView="bg-gray-50 dark:bg-gray-900 p-4"
      input="border-2 border-blue-400 rounded-xl"
    />
  );
}

Props Override#

Pass an object to override specific props on the default component. This is useful for adding className, event handlers, data attributes, or any other prop the default component accepts.

<CopilotChat
  messageView={{
    className: "my-custom-messages",
    "data-testid": "message-view",
  }}
  input={{ autoFocus: true }}
/>

Custom Components#

For full control, pass your own React component. It receives all the same props as the default component.

import { CopilotChat } from "@copilotkit/react-core/v2";

const CustomMessageView = ({ messages, isRunning }) => (
  <div className="space-y-4 p-6">
    {messages?.map((msg) => (
      <div
        key={msg.id}
        className={msg.role === "user" ? "text-right" : "text-left"}
      >
        {msg.content}
      </div>
    ))}
    {isRunning && <div className="animate-pulse">Thinking...</div>}
  </div>
);

export function Chat() {
  return (
    <CopilotChat messageView={CustomMessageView} />
  );
}

Nested Slots (Drill-Down)#

Slots are recursive. You can customize sub-components at any depth by nesting objects.

Two levels deep#

Override the assistant message's toolbar within the message view:

<CopilotChat
  messageView={{
    assistantMessage: {
      toolbar: CustomToolbar,
      copyButton: CustomCopyButton,
    },
    userMessage: CustomUserMessage,
  }}
/>

Three levels deep#

Override a specific button inside the assistant message toolbar:

<CopilotChat
  messageView={{
    assistantMessage: {
      copyButton: ({ onClick }) => <button onClick={onClick}>Copy</button>,
    },
  }}
/>

Input sub-slots#

<CopilotChat
  input={{
    textArea: CustomTextArea,
    sendButton: CustomSendButton,
  }}
/>

Scroll view sub-slots#

<CopilotChat
  scrollView={{
    feather: CustomFeather,
    scrollToBottomButton: CustomScrollButton,
  }}
/>

Suggestion view sub-slots#

<CopilotChat
  suggestionView={{
    suggestion: CustomSuggestionPill,
    container: CustomSuggestionContainer,
  }}
/>

Children Render Function#

For complete layout control, use the children render function pattern. This gives you pre-built slot elements that you can arrange however you want.

import { CopilotChat } from "@copilotkit/react-core/v2";

export function Chat() {
  return (
    <CopilotChat>
      {({ messageView, input, scrollView, suggestionView }) => (
        <div className="flex flex-col h-full">
          <header className="p-4 border-b font-semibold">My Agent</header>
          {scrollView}
          <div className="border-t p-4">{input}</div>
        </div>
      )}
    </CopilotChat>
  );
}

Reshaping the Message List#

Slots change how each message renders. To change which messages render — hide some, replace them, reorder them — pass transformMessages to the message view. It receives the whole list and returns the list to render.

import { useCallback } from "react";
import { CopilotChat, type Message } from "@copilotkit/react-core/v2";

export function Chat() {
  const transformMessages = useCallback(
    (messages: Message[]) => messages.filter((m) => m.role !== "tool"),
    [],
  );

  return <CopilotChat messageView={{ transformMessages }} />;
}

A few things to know:

• Long threads stay virtualized. Once a thread passes 50 messages the chat only mounts the rows on screen. It counts the messages transformMessages returns, so hidden messages take no row.
• Tool cards keep their results. Tool-call renderers look up results in the full list, so hiding tool-result messages, as above, does not empty the cards that display them.
• Keep ids unique and stable. Return each message id at most once. A message you build yourself, such as one that stands in for several, needs its own id, and that id must stay the same while the thread streams. Derive it from something fixed, like the id of the first message it replaces. The chat uses the last message you return to decide which one is still streaming.
• Pass a stable function. The transform reruns whenever the messages or the function change. An inline function works, but reruns on every render.

If you pass the message view a children render function to lay out the rendered messages yourself, virtualization turns off and every message is mounted. Prefer transformMessages for list-level changes; in development the chat warns when children is what turned virtualization off.

Labels#

Customize any text string in the UI via the labels prop. This does not use the slot system — it's a separate convenience prop on CopilotChat, CopilotSidebar, and CopilotPopup.

<CopilotChat
  labels={{
    chatInputPlaceholder: "Ask your agent anything...",
    welcomeMessageText: "How can I help you today?",
    chatDisclaimerText: "AI responses may be inaccurate.",
  }}
/>

Available Slots#

CopilotChat / CopilotSidebar / CopilotPopup#

These are the root-level slot props available on all chat components:

CopilotSidebar and CopilotPopup also have:

messageView sub-slots#

Available via messageView={{ ... }}:

assistantMessage sub-slots#

Available via messageView={{ assistantMessage: { ... } }}:

userMessage sub-slots#

Available via messageView={{ userMessage: { ... } }}:

reasoningMessage sub-slots#

Available via messageView={{ reasoningMessage: { ... } }}:

input sub-slots#

Available via input={{ ... }}:

scrollView sub-slots#

Available via scrollView={{ ... }}:

suggestionView sub-slots#

Available via suggestionView={{ ... }}:

welcomeScreen sub-slots#

Available via welcomeScreen={{ ... }}:

header sub-slots (Sidebar/Popup only)#

Available via header={{ ... }}:

toggleButton sub-slots (Sidebar/Popup only)#

Available via toggleButton={{ ... }}: