# useCopilotChatConfiguration

> React hook and provider for chat UI configuration and labels

## Overview [#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.

Wrap your chat in `CopilotChatConfigurationProvider` to change its labels, bind it to an agent and thread, or control its modal. Read those values in any child with `useCopilotChatConfiguration`. [`CopilotChat`](/reference/components/CopilotChat) wraps its children in this provider.

## CopilotChatConfigurationProvider [#copilotchatconfigurationprovider]

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

### Signature [#signature]

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

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

### Props [#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 label you do not set comes from the
  parent provider, then from the built-in defaults. 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 the `agentId` on `CopilotKitProvider`, 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" default="true">
  The initial open state of the modal. When you set it, this provider owns its
  modal state. If omitted, the provider uses the parent provider state, or
  `true` when there is no parent.
</PropertyReference>

## useCopilotChatConfiguration [#usecopilotchatconfiguration]

### Signature [#signature-1]

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

function useCopilotChatConfiguration(): CopilotChatConfigurationValue | null;
```

### Parameters [#parameters]

This hook takes no parameters.

### Return Value [#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">
  The current modal open state.
</PropertyReference>

  <PropertyReference name="setModalOpen" type="(open: boolean) => void">
    Function to control the modal open state.
  </PropertyReference>
</PropertyReference>

## CopilotChatLabels [#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 attachments"`                                            |
| `chatInputToolbarToolsButtonLabel`            | `"Tools"`                                                      |
| `chatInputToolbarSendButtonLabel`             | `"Send message"`                                               |
| `chatInputToolbarStopButtonLabel`             | `"Stop"`                                                       |
| `assistantMessageToolbarCopyCodeLabel`        | `"Copy"`                                                       |
| `assistantMessageToolbarCopyCodeCopiedLabel`  | `"Copied"`                                                     |
| `assistantMessageToolbarCopyMessageLabel`     | `"Copy"`                                                       |
| `assistantMessageToolbarThumbsUpLabel`        | `"Good response"`                                              |
| `assistantMessageToolbarThumbsDownLabel`      | `"Bad response"`                                               |
| `assistantMessageFeedbackCommentPlaceholder`  | `"Add a comment (optional)"`                                   |
| `assistantMessageFeedbackCommentSubmitLabel`  | `"Send comment"`                                               |
| `assistantMessageToolbarReadAloudLabel`       | `"Read aloud"`                                                 |
| `assistantMessageToolbarRegenerateLabel`      | `"Regenerate"`                                                 |
| `userMessageToolbarCopyMessageLabel`          | `"Copy"`                                                       |
| `userMessageToolbarEditMessageLabel`          | `"Edit"`                                                       |
| `userMessageToolbarPreviousBranchLabel`       | `"Previous branch"`                                            |
| `userMessageToolbarNextBranchLabel`           | `"Next branch"`                                                |
| `chatDisclaimerText`                          | `"AI can make mistakes. Please verify important information."` |
| `chatToggleOpenLabel`                         | `"Open chat"`                                                  |
| `chatToggleCloseLabel`                        | `"Close chat"`                                                 |
| `chatScrollToBottomLabel`                     | `"Scroll to bottom"`                                           |
| `modalHeaderTitle`                            | `"CopilotKit Chat"`                                            |
| `welcomeMessageText`                          | `"How can I help you today?"`                                  |
| `reasoningMessageThinkingLabel`               | `"Thinking…"`                                                  |
| `chatInputSlashMenuLabel`                     | `"Slash commands"`                                             |
| `chatInputSlashMenuEmptyText`                 | `"No commands found"`                                          |
| `attachmentRemoveButtonLabel`                 | `"Remove attachment"`                                          |
| `attachmentPlayVideoButtonLabel`              | `"Play video"`                                                 |
| `attachmentPreviewCloseButtonLabel`           | `"Close preview"`                                              |
| `modalHeaderCloseButtonLabel`                 | `"Close"`                                                      |
| `modalHeaderThreadsButtonLabel`               | `"Open threads"`                                               |
| `sidebarLabel`                                | `"Copilot chat sidebar"`                                       |

## Usage [#usage]

### Basic Label Customization [#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 [#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 [#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 [#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 [#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 [#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 the `agentId` on `CopilotKitProvider`, then to `"default"`. [`useSuggestions`](/reference/hooks/useSuggestions) reads this `agentId` when you do not pass one.
- **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**: A provider that sets `isModalDefaultOpen` owns its modal state (`isModalOpen` and `setModalOpen`). A nested provider without this prop uses the parent state. A top-level provider without this prop owns its state, and the modal starts open.
- **Null Return**: The hook returns `null` when used outside any `CopilotChatConfigurationProvider`, rather than throwing an error. Components should handle this case.
