useCopilotChatConfiguration

React hook and provider for chat UI configuration and labels

Overview

useCopilotChatConfiguration is a React hook that reads the chat configuration context. It returns the configuration value from the nearest CopilotChatConfigurationProvider, or null if no provider is present.

This page documents both the hook and the CopilotChatConfigurationProvider component, which together provide a lightweight context for localized labels, agent/thread binding, and modal state used by the chat UI components.

CopilotChatConfigurationProvider

A provider component that exposes localized labels, agent and thread IDs, and optional modal state to all descendant chat components.

Signature

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

<CopilotChatConfigurationProvider
  labels={...}
  agentId="my-agent"
  threadId="thread-123"
  isModalDefaultOpen={true}
>
  {children}
</CopilotChatConfigurationProvider>

Props

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

useCopilotChatConfiguration

Signature

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

function useCopilotChatConfiguration(): CopilotChatConfigurationValue | null;

Parameters

This hook takes no parameters.

Return Value

Returns null if used outside of a CopilotChatConfigurationProvider. Otherwise returns a CopilotChatConfigurationValue object:

Prop

Type

CopilotChatLabels

The CopilotChatLabels type defines all customizable text strings used by the chat UI. The following keys are available with their default values:

Key	Default Value
`chatInputPlaceholder`	`"Type a message..."`
`chatInputToolbarStartTranscribeButtonLabel`	`"Transcribe"`
`chatInputToolbarCancelTranscribeButtonLabel`	`"Cancel"`
`chatInputToolbarFinishTranscribeButtonLabel`	`"Finish"`
`chatInputToolbarAddButtonLabel`	`"Add photos or files"`
`chatInputToolbarToolsButtonLabel`	`"Tools"`
`assistantMessageToolbarCopyCodeLabel`	`"Copy"`
`assistantMessageToolbarCopyCodeCopiedLabel`	`"Copied"`
`assistantMessageToolbarCopyMessageLabel`	`"Copy"`
`assistantMessageToolbarThumbsUpLabel`	`"Good response"`
`assistantMessageToolbarThumbsDownLabel`	`"Bad response"`
`assistantMessageToolbarReadAloudLabel`	`"Read aloud"`
`assistantMessageToolbarRegenerateLabel`	`"Regenerate"`
`userMessageToolbarCopyMessageLabel`	`"Copy"`
`userMessageToolbarEditMessageLabel`	`"Edit"`
`chatDisclaimerText`	`"AI can make mistakes. Please verify important information."`
`chatToggleOpenLabel`	`"Open chat"`
`chatToggleCloseLabel`	`"Close chat"`
`modalHeaderTitle`	`"CopilotKit Chat"`
`welcomeMessageText`	`"How can I help you today?"`

Usage

Basic Label Customization

import {
  CopilotChatConfigurationProvider,
  useCopilotChatConfiguration,
} from "@copilotkit/react-core/v2";

function App() {
  return (
    <CopilotChatConfigurationProvider
      labels={{
        chatInputPlaceholder: "Ask me anything...",
        modalHeaderTitle: "AI Assistant",
        welcomeMessageText: "Hello! What can I do for you?",
        chatDisclaimerText: "Responses are AI-generated.",
      }}
    >
      <ChatUI />
    </CopilotChatConfigurationProvider>
  );
}

Reading Configuration in a Component

function ChatHeader() {
  const config = useCopilotChatConfiguration();

  if (!config) {
    return <h2>Chat</h2>;
  }

  return <h2>{config.labels.modalHeaderTitle}</h2>;
}

Binding to a Specific Agent and Thread

function SupportChat() {
  return (
    <CopilotChatConfigurationProvider
      agentId="support-agent"
      threadId="ticket-456"
      labels={{
        chatInputPlaceholder: "Describe your issue...",
        modalHeaderTitle: "Support Chat",
      }}
    >
      <ChatWindow />
    </CopilotChatConfigurationProvider>
  );
}

Modal State Management

import {
  CopilotChatConfigurationProvider,
  useCopilotChatConfiguration,
} from "@copilotkit/react-core/v2";

function App() {
  return (
    <CopilotChatConfigurationProvider isModalDefaultOpen={false}>
      <ToggleButton />
      <ChatModal />
    </CopilotChatConfigurationProvider>
  );
}

function ToggleButton() {
  const config = useCopilotChatConfiguration();

  if (!config?.setModalOpen) return null;

  return (
    <button onClick={() => config.setModalOpen!(!config.isModalOpen)}>
      {config.isModalOpen
        ? config.labels.chatToggleCloseLabel
        : config.labels.chatToggleOpenLabel}
    </button>
  );
}

Nested Providers

Providers can be nested. Child providers inherit and merge labels from their parent, with child overrides taking precedence.

function App() {
  return (
    <CopilotChatConfigurationProvider
      labels={{ chatDisclaimerText: "Company-wide disclaimer." }}
    >
      <CopilotChatConfigurationProvider
        agentId="sales"
        labels={{ modalHeaderTitle: "Sales Assistant" }}
      >
        {/* This context has both the company disclaimer and the sales title */}
        <SalesChat />
      </CopilotChatConfigurationProvider>
    </CopilotChatConfigurationProvider>
  );
}

Behavior

Label Merging: Labels are merged in order: built-in defaults, then parent provider labels, then current provider labels. This allows partial overrides at any level.
Agent ID Resolution: The agentId resolves from the nearest provider, falling back to parent providers, then to "default".
Thread ID Generation: If no threadId is provided at any level, a random UUID is generated and remains stable for the lifetime of the provider.
Modal State Ownership: Modal state (isModalOpen / setModalOpen) is only created when a provider explicitly sets isModalDefaultOpen. Providers without this prop pass through the parent's modal state.
Null Return: The hook returns null when used outside any CopilotChatConfigurationProvider, rather than throwing an error. Components should handle this case gracefully.

Related

useSuggestions -- Uses CopilotChatConfigurationProvider context for agent ID resolution
CopilotChat -- Chat component that wraps its children with this provider