CSS Customization
Theme CopilotKit components via CSS variables and class overrides.
Not available for agent-spec yet
chat-customization-css demo, and agent-spec doesn't have it yet. See this page for CopilotKit's Built-in Agent, LangGraph (Python), LangGraph (TypeScript).What is this?
CopilotKit has a variety of ways to customize the colors and structure of the Copilot UI components via plain CSS. You can:
- Override CopilotKit CSS variables to re-tint the whole UI
- Target the built-in class names (
.copilotKit...) for structural tweaks - Swap fonts per surface (messages, input, bubbles)
- Replace icons and labels via component props
This page is for the v2 components from @copilotkit/react-core/v2. Parts
marked v1 apply only to the deprecated v1 package, @copilotkit/react-ui.
If you need to change behavior, not just look, see slots or fully headless UI.
Scoping the theme
The demo keeps all of its styling in a sibling theme.css file and applies it
only to the wrapper div holding <CopilotChat>. Importing the stylesheet from
the page module is enough; Next.js bundles it with the route:
Scoping every selector under a wrapper class keeps the overrides from leaking into the rest of the app.
CSS Variables (Easiest)
The v2 components that the demo uses read the shadcn tokens listed in
v2 design tokens. The demo overrides these tokens
on the [data-copilotkit] element inside its scope wrapper:
The v1 components (@copilotkit/react-ui) read the --copilot-kit-* variables
below instead. For v1 only, you can also apply the overrides inline via the
CopilotKitCSSProperties helper:
import { CopilotKitCSSProperties } from "@copilotkit/react-ui";
<div
style={
{
"--copilot-kit-primary-color": "#222222",
} as CopilotKitCSSProperties
}
>
<CopilotSidebar />
</div>In v2, set the same color with a CSS rule on the [data-copilotkit] element:
.my-chat [data-copilotkit] {
--primary: #222222;
}Reference
| CSS Variable | Description |
|---|---|
--copilot-kit-primary-color | Main brand/action color for buttons and interactive elements |
--copilot-kit-contrast-color | Color that contrasts with primary, used for text on primary elements |
--copilot-kit-background-color | Main page/container background color |
--copilot-kit-secondary-color | Secondary background for cards, panels, and elevated surfaces |
--copilot-kit-secondary-contrast-color | Primary text color for main content |
--copilot-kit-separator-color | Border color for dividers and containers |
--copilot-kit-muted-color | Muted color for disabled/inactive states |
--copilot-kit-shadow-sm / -md / -lg | Elevation shadows for subtle surfaces, cards, and modals |
Two token systems
The --copilot-kit-* variables above style the v1 component CSS
(@copilotkit/react-ui). The v2 components
(@copilotkit/react-core/v2) are Tailwind + shadcn-based and use a
separate set of design tokens. See v2 design
tokens below.
v2 Design Tokens (shadcn)
The v2 components (@copilotkit/react-core/v2) ship a Tailwind v4 theme built
on the standard shadcn/ui token set. Instead of the --copilot-kit-*
variables, they read oklch color tokens that are scoped to
the [data-copilotkit] root and wired into Tailwind utilities through an
@theme inline block. This means you can re-skin the entire v2 UI by
overriding a handful of CSS custom properties. Every component uses the new
values.
Override them with a selector that matches the [data-copilotkit] element,
the same way you would in a shadcn project. A value set only on an ancestor has
no effect, because CopilotKit declares each token on that element:
[data-copilotkit] {
--primary: oklch(0.55 0.22 264); /* accent / action color */
--primary-foreground: oklch(0.99 0 0); /* text on primary */
--background: oklch(1 0 0); /* surface background */
--foreground: oklch(0.145 0 0); /* primary text */
--muted: oklch(0.97 0 0); /* subtle backgrounds */
--border: oklch(0.922 0 0); /* dividers, outlines */
--radius: 0.625rem; /* global corner radius */
}
/* Dark mode is keyed off a `.dark` ancestor */
.dark [data-copilotkit] {
--background: oklch(0.145 0 0);
--foreground: oklch(0.985 0 0);
--border: oklch(0.269 0 0);
}Reference
These are the most commonly overridden v2 tokens. Each light value has a
matching dark-mode value under .dark [data-copilotkit]. The full set
(popover, accent, destructive, chart, and sidebar variants) lives in
@copilotkit/react-core/v2/styles.css.
| Token | Description |
|---|---|
--background / --foreground | Base surface background and primary text color |
--primary / --primary-foreground | Accent/action color and the text rendered on top of it |
--secondary / --secondary-foreground | Secondary surfaces (cards, panels) and their text |
--muted / --muted-foreground | Subtle backgrounds and de-emphasized text |
--accent / --accent-foreground | Hover/active states and their text |
--border / --input / --ring | Divider/outline color, input borders, focus ring |
--destructive / --destructive-foreground | Error/danger color and its text |
--card / --popover (+ -foreground) | Elevated surface backgrounds and their text |
--sidebar-* | The sidebar's own background/foreground/border/ring set |
--radius | Base corner radius; --radius-sm/md/lg/xl derive from it |
oklch values
v2 tokens use the oklch() color space, which keeps perceived lightness
consistent across hues. You can still pass hsl(), rgb(), or hex; any
valid CSS color works.
Custom CSS
The CopilotKit CSS is structured to allow customization via CSS classes. You can target specific pieces of the UI from your own stylesheet:
.copilotKitButton {
border-radius: 0;
}
.copilotKitMessages {
padding: 2rem;
}
.copilotKitUserMessage {
background: #007AFF;
}The demo's theme.css wraps every selector under .chat-css-demo-scope so
the overrides don't leak out. Here's the user message bubble block from
that file:
Reference
| CSS Class | Description |
|---|---|
.copilotKitMessages | Main container for all chat messages |
.copilotKitMessage | Base class applied to every message bubble (user and assistant) |
.copilotKitInput | Text input container with typing area and send button |
.copilotKitUserMessage | Styling for user messages |
.copilotKitAssistantMessage | Styling for AI responses |
.copilotKitHeader | Top bar of chat window containing title and controls |
.copilotKitButton | Primary chat toggle button |
.copilotKitWindow | Root container defining overall chat window dimensions |
.copilotKitMarkdown | Styles for rendered markdown content (v1 only) |
.copilotKitCodeBlock | Code snippet container with syntax highlighting (v1 only) |
.copilotKitSidebar | Styles for sidebar chat mode |
.copilotKitPopup | Styles for popup chat mode |
Custom Fonts
You can customize the fonts by updating the font-family property on the
relevant CopilotKit classes:
.copilotKitMessages {
font-family: Arial, sans-serif;
}
.copilotKitInput {
font-family: Arial, sans-serif;
}Custom Icons
In the v1 components (@copilotkit/react-ui), pass the icons prop to
CopilotSidebar, CopilotPopup, or CopilotChat. The v2 components have no
icons prop. To replace their toggle button or header, use
slots.
<CopilotChat
icons={{
openIcon: <YourOpenIconComponent />,
closeIcon: <YourCloseIconComponent />,
}}
/>Custom Labels
Customize all user-facing copy via the labels prop:
<CopilotChat
labels={{
welcomeMessageText: "Hello! How can I help you today?",
modalHeaderTitle: "My Copilot",
chatInputPlaceholder: "Ask me anything!",
}}
/>How is this guide?