---
title: "useCopilotChatConfiguration"
description: "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

```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>

## useCopilotChatConfiguration

### 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>
  );
}
```

### Modal State Management

```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" }}
      >
        {/* 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`](/reference/hooks/useSuggestions) -- Uses `CopilotChatConfigurationProvider` context for agent ID resolution
- [`CopilotChat`](/reference/components/CopilotChat) -- Chat component that wraps its children with this provider
