Skip to content

useCopilotChatConfiguration.mdx

Latest commit

 

History

History
255 lines (201 loc) · 9.71 KB

useCopilotChatConfiguration.mdx

File metadata and controls

255 lines (201 loc) · 9.71 KB
Raw
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

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

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

Props

The child components that will have access to the chat configuration context. 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. The agent ID to associate with this chat context. Falls back to the parent provider's `agentId`, then to `"default"`. The thread ID for conversation continuity. If omitted, falls back to the parent provider's `threadId`, or a new random UUID is generated. 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).

useCopilotChatConfiguration

Signature

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:

The resolved chat configuration. The fully resolved labels object, merged from 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. The current modal open state. `undefined` if no provider in the tree has created modal state via `isModalDefaultOpen`. Function to control the modal open state. `undefined` if no provider in the tree has created modal state.

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

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

function ChatHeader() {
  const config = useCopilotChatConfiguration();

  if (!config) {
    return <h2>Chat</h2>;
  }

  return <h2>{config.labels.modalHeaderTitle}</h2>;
}

Binding to a Specific Agent and Thread

function SupportChat() {
  return (
    <CopilotChatConfigurationProvider
      agentId="support-agent"
      threadId="ticket-456"
      labels={{
        chatInputPlaceholder: "Describe your issue...",
        modalHeaderTitle: "Support Chat",
      }}
    >
      <ChatWindow />
    </CopilotChatConfigurationProvider>
  );
}

Modal State Management

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.

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 -- Uses CopilotChatConfigurationProvider context for agent ID resolution
  • CopilotChat -- Chat component that wraps its children with this provider