Skip to content

useCopilotChatConfiguration.mdx

Latest commit

 

History

History
303 lines (240 loc) · 13.2 KB

useCopilotChatConfiguration.mdx

File metadata and controls

303 lines (240 loc) · 13.2 KB
Raw
title useCopilotChatConfiguration
description Vue 3 composable for reading reactive chat UI configuration and labels

Overview

useCopilotChatConfiguration is a Vue 3 composable that reads the chat configuration context injected by the nearest CopilotChatConfigurationProvider. That provider is mounted automatically by the CopilotKit chat components (CopilotChat, CopilotPopup, and CopilotSidebar) — CopilotKitProvider does not mount it — or you can mount it directly. 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, or the modal state change, the resolved value updates automatically. This provides a lightweight, reactive context for localized labels, agent/thread binding, and modal state used by the chat UI components.

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.

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

<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

Partial set of label overrides. Any labels not provided fall back to the built-in defaults, then to any parent provider's labels. See [CopilotChatLabels](#copilotchatlabels) below for all available keys. The agent ID to associate with this chat context. Falls back to the parent provider's `agentId`, then to the default agent ID (`"default"`). 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. 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. When provided, this provider owns modal open/close state and uses this value as the initial state. If omitted, modal state is inherited from the parent provider (if any).

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

useCopilotChatConfiguration

Signature

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

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

Parameters

This composable takes no parameters.

Return Value

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

The fully resolved labels object, merged from built-in defaults, parent providers, and the nearest provider's overrides. See [CopilotChatLabels](#copilotchatlabels) for all keys. The resolved agent ID for this chat context. The resolved thread ID for this chat context. `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`. The current modal open state. `undefined` if no provider in the tree owns modal state via `isModalDefaultOpen`. Function to control the modal open state. `undefined` if no provider in the tree owns modal state.

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

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.

<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

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

<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

<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

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.

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

Nested Providers

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

<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

  • 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.
  • Null resolution: The returned ref resolves to null when used outside any CopilotChatConfigurationProvider, rather than throwing. Components should handle this case gracefully.

Related

  • useCopilotKit - access the underlying CopilotKit instance
  • CopilotKitProvider - provides the CopilotKit instance to descendant composables (the chat configuration context is mounted by the chat components, not by CopilotKitProvider)