# useCopilotChatConfiguration

> Vue 3 composable for reading reactive chat UI configuration and labels

## Overview [#overview]

`useCopilotChatConfiguration` is a Vue 3 composable that reads the chat configuration context injected by the nearest `CopilotChatConfigurationProvider`. [`CopilotChat`](/reference/vue/components/CopilotChat), [`CopilotPopup`](/reference/vue/components/CopilotPopup), and [`CopilotSidebar`](/reference/vue/components/CopilotSidebar) mount this provider for you. [`CopilotKitProvider`](/reference/vue/components/CopilotKitProvider) does **not** mount it. You can also mount it yourself. It returns a `ComputedRef` that resolves to the current `CopilotChatConfigurationValue`, or `null` when no provider is present in the component tree.

Because the composable returns a `ComputedRef`, the value stays reactive: when labels, the active agent or thread, the modal state, or the drawer state change, the resolved value updates automatically. This provides a lightweight, reactive context for localized labels, agent/thread binding, modal state, and the shared drawer controls used by the chat UI components.

<Callout type="info">
  Like all Vue composables, call `useCopilotChatConfiguration` synchronously
  inside `<script setup>` or a `setup()` function so the injection resolves
  against the surrounding component tree. The returned ref resolves to `null`
  when no `CopilotChatConfigurationProvider` (or a CopilotKit chat component that
  mounts one) is an ancestor, so guard against that case rather than assuming a
  value.
</Callout>

## CopilotChatConfigurationProvider [#copilotchatconfigurationprovider]

A provider component that injects localized labels, agent and thread IDs, and optional modal state for all descendant chat components. The CopilotKit chat components (`CopilotChat`, `CopilotPopup`, `CopilotSidebar`) mount one automatically, so you only need to mount it directly when you want to read configuration outside a chat component, or scope or override configuration for a subtree.

### Usage [#usage]

```vue
<script setup lang="ts">
import { CopilotChatConfigurationProvider } from "@copilotkit/vue/v2";
</script>

<template>
  <CopilotChatConfigurationProvider
    :labels="{ chatInputPlaceholder: 'Ask me anything...' }"
    agent-id="my-agent"
    thread-id="thread-123"
    :is-modal-default-open="true"
  >
    <slot />
  </CopilotChatConfigurationProvider>
</template>
```

### Props [#props]

<PropertyReference name="labels" type="Partial<CopilotChatLabels>">
  Partial set of label overrides. Any labels not provided come from the parent
  provider, then from the built-in defaults. See
  [CopilotChatLabels](#copilotchatlabels) 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 default agent ID (`"default"`).
</PropertyReference>

<PropertyReference name="threadId" type="string">
  The thread ID for conversation continuity. If omitted, falls back to the
  parent provider's `threadId`, otherwise a random UUID is generated and remains
  stable for the lifetime of the provider.
</PropertyReference>

<PropertyReference name="hasExplicitThreadId" type="boolean">
  Marks whether the supplied `threadId` is a real caller choice rather than an
  internally minted UUID. When omitted, the provider infers explicitness from
  whether `threadId` itself was supplied. This is primarily for internal
  wrappers; most applications can leave it unset.
</PropertyReference>

<PropertyReference name="isModalDefaultOpen" type="boolean">
  When provided, this provider owns modal open/close state. It starts from the
  parent's open state when a parent owns one, and from this value when not. If
  omitted, modal state is inherited from the parent provider (if any).
</PropertyReference>

The injected configuration value also carries shared drawer state and thread
control helpers, which are documented in the composable return value below.

The provider renders its default `<slot />`, so descendant components placed inside it receive the injected configuration.

## useCopilotChatConfiguration [#usecopilotchatconfiguration]

### Signature [#signature]

```ts
import { useCopilotChatConfiguration } from "@copilotkit/vue/v2";
import type { ComputedRef } from "vue";
import type { CopilotChatConfigurationValue } from "@copilotkit/vue/v2";

function useCopilotChatConfiguration(): ComputedRef<
  CopilotChatConfigurationValue | null
>;
```

### Parameters [#parameters]

This composable takes no parameters.

### Return Value [#return-value]

Returns a `ComputedRef`. Its `.value` is `null` when the composable is used outside any `CopilotChatConfigurationProvider`, and otherwise a `CopilotChatConfigurationValue` object:

<PropertyReference name="labels" type="CopilotChatLabels">
  The fully resolved labels object, merged from built-in 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="hasExplicitThreadId" type="boolean">
  `true` when the resolved `threadId` was chosen by the caller (or a parent
  provider) rather than silently minted inside the provider chain. Consumers
  that only make sense against a real backend thread should gate on this instead
  of `!!threadId`.
</PropertyReference>

<PropertyReference name="isModalOpen" type="boolean | undefined">
  The current modal open state. `undefined` if no provider in the tree owns
  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 owns modal state.
</PropertyReference>

<PropertyReference name="drawerOpen" type="boolean">
  The current threads drawer state. This is always available when a provider is
  present.
</PropertyReference>

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

<PropertyReference name="drawerRegistered" type="boolean">
  `true` when a threads drawer is mounted in the current provider chain.
</PropertyReference>

<PropertyReference name="registerDrawer" type="() => () => void">
  Registers a threads drawer and returns a cleanup function that unregisters
  it.
</PropertyReference>

<PropertyReference name="setActiveThreadId" type="(threadId: string, options?: { explicit?: boolean }) => void">
  Switches the active thread from code. `options.explicit` defaults to `true`,
  which marks the thread as a caller choice. If the provider has a `threadId`
  prop, the call does nothing and logs a warning.
</PropertyReference>

<PropertyReference name="startNewThread" type="() => void">
  Resets the current chat to a fresh, non-explicit thread. If the provider has a
  `threadId` prop, the call does nothing and logs a warning.
</PropertyReference>

## CopilotChatLabels [#copilotchatlabels]

The `CopilotChatLabels` type defines all customizable text strings used by the chat UI. The type is derived from `CopilotChatDefaultLabels`. 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"`                                                      |
| `chatInputToolbarSendButtonLabel`             | `"Send message"`                                               |
| `chatInputToolbarStopButtonLabel`             | `"Stop"`                                                       |
| `assistantMessageToolbarCopyCodeLabel`        | `"Copy"`                                                       |
| `assistantMessageToolbarCopyCodeCopiedLabel`  | `"Copied"`                                                     |
| `assistantMessageToolbarCopyMessageLabel`     | `"Copy"`                                                       |
| `assistantMessageToolbarThumbsUpLabel`        | `"Good response"`                                              |
| `assistantMessageToolbarThumbsDownLabel`      | `"Bad response"`                                               |
| `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-1]

### Reading Configuration in a Component [#reading-configuration-in-a-component]

Call the composable once, then read from the returned ref. Guard against `null` for the case where no provider is present.

```vue
<script setup lang="ts">
import { useCopilotChatConfiguration } from "@copilotkit/vue/v2";

const config = useCopilotChatConfiguration();
</script>

<template>
  <h2 v-if="config">{{ config.labels.modalHeaderTitle }}</h2>
  <h2 v-else>Chat</h2>
</template>
```

### Basic Label Customization [#basic-label-customization]

Scope label overrides by mounting a provider around the chat UI.

```vue
<script setup lang="ts">
import { CopilotChatConfigurationProvider } from "@copilotkit/vue/v2";
import ChatUI from "./ChatUI.vue";

const labels = {
  chatInputPlaceholder: "Ask me anything...",
  modalHeaderTitle: "AI Assistant",
  welcomeMessageText: "Hello! What can I do for you?",
  chatDisclaimerText: "Responses are AI-generated.",
};
</script>

<template>
  <CopilotChatConfigurationProvider :labels="labels">
    <ChatUI />
  </CopilotChatConfigurationProvider>
</template>
```

### Binding to a Specific Agent and Thread [#binding-to-a-specific-agent-and-thread]

```vue
<script setup lang="ts">
import { CopilotChatConfigurationProvider } from "@copilotkit/vue/v2";
import ChatWindow from "./ChatWindow.vue";
</script>

<template>
  <CopilotChatConfigurationProvider
    agent-id="support-agent"
    thread-id="ticket-456"
    :labels="{
      chatInputPlaceholder: 'Describe your issue...',
      modalHeaderTitle: 'Support Chat',
    }"
  >
    <ChatWindow />
  </CopilotChatConfigurationProvider>
</template>
```

### Modal State Management [#modal-state-management]

When a provider sets `is-modal-default-open`, descendants can read `isModalOpen` and call `setModalOpen`. Because the composable returns a `ComputedRef`, the toggle stays in sync automatically.

```vue
<!-- App.vue -->
<script setup lang="ts">
import { CopilotChatConfigurationProvider } from "@copilotkit/vue/v2";
import ToggleButton from "./ToggleButton.vue";
import ChatModal from "./ChatModal.vue";
</script>

<template>
  <CopilotChatConfigurationProvider :is-modal-default-open="false">
    <ToggleButton />
    <ChatModal />
  </CopilotChatConfigurationProvider>
</template>
```

```vue
<!-- ToggleButton.vue -->
<script setup lang="ts">
import { useCopilotChatConfiguration } from "@copilotkit/vue/v2";

const config = useCopilotChatConfiguration();

function toggle() {
  const value = config.value;
  if (!value?.setModalOpen) return;
  value.setModalOpen(!value.isModalOpen);
}
</script>

<template>
  <button v-if="config?.setModalOpen" @click="toggle">
    {{
      config.isModalOpen
        ? config.labels.chatToggleCloseLabel
        : config.labels.chatToggleOpenLabel
    }}
  </button>
</template>
```

### Drawer State Management [#drawer-state-management]

Use the shared drawer state when you need to open or close the threads drawer
from another component.

```vue
<!-- ToggleDrawer.vue -->
<script setup lang="ts">
import { useCopilotChatConfiguration } from "@copilotkit/vue/v2";

const config = useCopilotChatConfiguration();

function toggleDrawer() {
  const value = config.value;
  if (!value?.setDrawerOpen) return;
  value.setDrawerOpen(!value.drawerOpen);
}
</script>

<template>
  <button v-if="config" @click="toggleDrawer">
    {{ config.drawerOpen ? "Close drawer" : "Open drawer" }}
  </button>
</template>
```

### Nested Providers [#nested-providers]

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

```vue
<script setup lang="ts">
import { CopilotChatConfigurationProvider } from "@copilotkit/vue/v2";
import SalesChat from "./SalesChat.vue";
</script>

<template>
  <CopilotChatConfigurationProvider
    :labels="{ chatDisclaimerText: 'Company-wide disclaimer.' }"
  >
    <CopilotChatConfigurationProvider
      agent-id="sales"
      :labels="{ modalHeaderTitle: 'Sales Assistant' }"
    >
      <!-- This context has both the company disclaimer and the sales title -->
      <SalesChat />
    </CopilotChatConfigurationProvider>
  </CopilotChatConfigurationProvider>
</template>
```

## Behavior [#behavior]

- **Reactive ref**: The composable returns a `ComputedRef<CopilotChatConfigurationValue | null>`. Read it via `config.value` in script and `config` (auto-unwrapped) in templates. The value recomputes whenever the injected configuration changes.
- **Label merging**: Labels are merged in order: built-in defaults (`CopilotChatDefaultLabels`), then parent provider labels, then the current provider's labels. This allows partial overrides at any level.
- **Agent ID resolution**: `agentId` resolves from the nearest provider, falling back to parent providers, then to the default agent ID (`"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. `hasExplicitThreadId` reports whether the resolved thread ID was a caller choice rather than an internally minted UUID.
- **Modal state ownership**: Modal state (`isModalOpen` / `setModalOpen`) is only created when a provider sets `isModalDefaultOpen`. Providers without this prop pass through the parent's modal state, and both fields are `undefined` when no provider owns modal state.
- **Drawer state ownership**: Drawer state (`drawerOpen` / `setDrawerOpen`) is shared through the provider chain, and `drawerRegistered` / `registerDrawer` track whether a drawer is mounted so mobile launchers can appear.
- **Thread overrides**: `setActiveThreadId` and `startNewThread` are imperative helpers used by the threads drawer and other host UI. `hasExplicitThreadId` still determines whether the resolved thread is treated as caller-controlled.
- **Null resolution**: The returned ref resolves to `null` when used outside any `CopilotChatConfigurationProvider`, rather than throwing. Components should handle this case.
