useCopilotChatConfiguration

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

tsx

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

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

Props

<PropertyReference name="children" type="ReactNode" required> The child components that will have access to the chat configuration context. </PropertyReference> <PropertyReference name="labels" type="Partial<CopilotChatLabels>"> Partial set of label overrides. Any labels not provided will fall back to defaults, then to any parent provider's labels. See the [CopilotChatLabels](#copilotchatlabels) section below for all available keys. </PropertyReference> <PropertyReference name="agentId" type="string" default='"default"'> The agent ID to associate with this chat context. Falls back to the parent provider's `agentId`, then to `"default"`. </PropertyReference> <PropertyReference name="threadId" type="string"> The thread ID for conversation continuity. If omitted, falls back to the parent provider's `threadId`, or a new random UUID is generated. </PropertyReference> <PropertyReference name="isModalDefaultOpen" type="boolean"> When provided, creates modal open/close state within this provider. The initial value is used as the default state. If omitted, modal state is inherited from the parent provider (if any). </PropertyReference>

Signature

tsx

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:

<PropertyReference name="config" type="CopilotChatConfigurationValue"> The resolved chat configuration. <PropertyReference name="labels" type="CopilotChatLabels"> The fully resolved labels object, merged from defaults, parent providers, and the nearest provider's overrides. See [CopilotChatLabels](#copilotchatlabels) for all keys. </PropertyReference> <PropertyReference name="agentId" type="string"> The resolved agent ID for this chat context. </PropertyReference> <PropertyReference name="threadId" type="string"> The resolved thread ID for this chat context. </PropertyReference> <PropertyReference name="isModalOpen" type="boolean | undefined"> The current modal open state. `undefined` if no provider in the tree has created modal state via `isModalDefaultOpen`. </PropertyReference> <PropertyReference name="setModalOpen" type="((open: boolean) => void) | undefined"> Function to control the modal open state. `undefined` if no provider in the tree has created modal state. </PropertyReference> </PropertyReference>

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

tsx

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

tsx

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

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

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

Binding to a Specific Agent and Thread

tsx

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

tsx

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.

tsx

function App() {
  return (
    <CopilotChatConfigurationProvider
      labels={{ chatDisclaimerText: "Company-wide disclaimer." }}
    >
      <CopilotChatConfigurationProvider
        agentId="sales"
        labels={{ modalHeaderTitle: "Sales Assistant" }}
      >
        <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.

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

useCopilotChatConfiguration

Overview

CopilotChatConfigurationProvider

Signature

Props