use Copilot Chat Configuration
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.
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 wraps its children in this provider.
CopilotChatConfigurationProvider
A provider component that exposes localized labels, agent and thread IDs, and 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
Prop
Type
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:
Prop
Type
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
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
agentIdresolves from the nearest provider, falling back to parent providers, then to theagentIdonCopilotKitProvider, then to"default".useSuggestionsreads thisagentIdwhen you do not pass one. - Thread ID Generation: If no
threadIdis 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
isModalDefaultOpenowns its modal state (isModalOpenandsetModalOpen). 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
nullwhen used outside anyCopilotChatConfigurationProvider, rather than throwing an error. Components should handle this case.
How is this guide?