Migrate To 1.10.X

Overview

CopilotKit 1.10.X introduces a new headless UI system and simplified message formats. Most existing code will continue to work, but you may need to update custom message handling.

What you need to know:

• Message format has changed from classes to plain objects
• New headless UI hook available for advanced use cases
• Backwards compatibility maintained for most features

Key Improvements & Changes

Enhanced Message Format

Messages now use plain objects instead of classes for better performance and simpler handling.

Before

const message = new TextMessage({
  role: MessageRole.Assistant,
  content: "Hello, how are you?",
});

After

const message = {
  role: "assistant",
  content: "Hello, how are you?",
};

Simplified Message Type Checking

Message type checking has been streamlined for better developer experience. Instead of using the previous isTextMessage or adjacent methods, you can now check the role property of the message.

Before

if (message.isTextMessage()) {
  if (message.role === "assistant") {
    console.log(message.content);
  }
  if (message.role === "user") {
    console.log(message.content);
  }
}

if (message.isImageMessage()) {
  console.log(message.image);
}

if (message.isActionExecutionMessage()) {
  console.log(message.toolCalls);
}

// etc...

After

if (message.role === "assistant") {
  console.log(message.content, message.toolCalls, message.image);
}

if (message.role === "user") {
  console.log(message.content, message.image);
}

Custom Assistant Messages

Previously, you had to use the subComponent property to render custom assistant messages. Now you can use the generativeUI property instead.

Important! Both will continue to work.

Before

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

export const AssistantMessage = (props: AssistantMessageProps) => {
  const { message, subComponent } = props;

  return <div style={{ marginBottom: "0.5rem" }}>{subComponent}</div>;
};

After

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

export const AssistantMessage = (props: AssistantMessageProps) => {
  const { message } = props;

  return <div style={{ marginBottom: "0.5rem" }}>{message.generativeUI}</div>;
};

Backwards Compatibility

• Custom sub-components remain fully supported
• Both subComponent (legacy) and generativeUI (new) properties work
• Existing useCopilotChat code continues to function

New Features

Advanced Headless UI Hook

New useCopilotChatHeadless_c hook provides complete control over chat UI:

Features:

• Complete control over chat UI rendering
• Built-in generative UI support
• Advanced suggestions management
• Interrupt handling for human-in-the-loop workflows

<video src="https://cdn.copilotkit.ai/docs/copilotkit/videos/full-headless-chat.mp4" className="rounded-xl shadow-lg border" loop playsInline autoPlay muted />

An example of how you might use the new Headless UI hook:

const { messages, suggestions, interrupt } = useCopilotChatHeadless_c();

return (
  <div>
    {suggestions.map((suggestion) => (
      <div key={suggestion.id}>{suggestion.title}</div>
    ))}

    {interrupt}

    {messages.map((message) => {
      switch (message.role) {
        case "assistant":
          if (message.generativeUI) return message.generativeUI;
          return <div key={message.id}>{message.content}</div>;
        case "user":
          return <div key={message.id}>{message.content}</div>;
      }
    })}
  </div>
);

Read more about the new headless UI hook and get started.

What about useCopilotChat?

With the introduction of the new headless UI hook, we are starting the deprecation of useCopilotChat. While it will remain supported for several months in maintenance mode, all new headless UI features will be added to useCopilotChatHeadless_c.

We recommend migrating to the new hook for new projects. However, please feel free to continue using useCopilotChat until you are ready to migrate.

When to Migrate

Continue using useCopilotChat if:

• Your current implementation works well
• You don't need advanced headless features
• You prefer gradual migration

Migrate to useCopilotChatHeadless_c if:

• Starting a new project
• Building new headless UI implementations
• Need generative UI capabilities
• Want access to advanced suggestions and interrupts
• Building fully custom chat experiences