---
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
import { useCopilotChatConfiguration } from "@copilotkit/react-core/v2";

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
import { CopilotChatConfigurationProvider } from "@copilotkit/react-core/v2";

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
import { CopilotChatConfigurationProvider } from "@copilotkit/react-core/v2";

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