CSS Customization

Theme CopilotKit components via CSS variables and class overrides.

Chat Customization (CSS)

Waking up the demo

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:

page.tsx
import "./theme.css";

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:

theme.css
/* CopilotKit v2 reads these on the [data-copilotkit] root inside the chat.
 * Re-pointing them under our scope retints every Tailwind utility the
 * runtime renders (user message bubble, prose, borders, focus rings, …)
 * without us having to touch any individual class. */
.chat-css-demo-scope [data-copilotkit] {
  --background: var(--halcyon-paper);
  --foreground: var(--halcyon-ink);
  --card: var(--halcyon-card);
  --card-foreground: var(--halcyon-ink);
  --popover: var(--halcyon-paper-elevated);
  --popover-foreground: var(--halcyon-ink);
  --primary: var(--halcyon-ember);
  --primary-foreground: var(--halcyon-paper-elevated);
  --secondary: var(--halcyon-paper-soft);
  --secondary-foreground: var(--halcyon-ink);
  --muted: var(--halcyon-paper-soft);
  --muted-foreground: var(--halcyon-ink-mute);
  --accent: var(--halcyon-ember-soft);
  --accent-foreground: var(--halcyon-ember);
  --destructive: #b3361b;
  --destructive-foreground: var(--halcyon-paper-elevated);
  --border: var(--halcyon-rule);
  --input: var(--halcyon-rule);
  --ring: var(--halcyon-ember);
  --radius: 0px;
}

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:

globals.css
.my-chat [data-copilotkit] {
  --primary: #222222;
}

Reference

CSS VariableDescription
--copilot-kit-primary-colorMain brand/action color for buttons and interactive elements
--copilot-kit-contrast-colorColor that contrasts with primary, used for text on primary elements
--copilot-kit-background-colorMain page/container background color
--copilot-kit-secondary-colorSecondary background for cards, panels, and elevated surfaces
--copilot-kit-secondary-contrast-colorPrimary text color for main content
--copilot-kit-separator-colorBorder color for dividers and containers
--copilot-kit-muted-colorMuted color for disabled/inactive states
--copilot-kit-shadow-sm / -md / -lgElevation 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:

globals.css
[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.

TokenDescription
--background / --foregroundBase surface background and primary text color
--primary / --primary-foregroundAccent/action color and the text rendered on top of it
--secondary / --secondary-foregroundSecondary surfaces (cards, panels) and their text
--muted / --muted-foregroundSubtle backgrounds and de-emphasized text
--accent / --accent-foregroundHover/active states and their text
--border / --input / --ringDivider/outline color, input borders, focus ring
--destructive / --destructive-foregroundError/danger color and its text
--card / --popover (+ -foreground)Elevated surface backgrounds and their text
--sidebar-*The sidebar's own background/foreground/border/ring set
--radiusBase 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:

globals.css
.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:

theme.css
/* User message — a "transmission" in JetBrains Mono on a paper card. The
 * outer wrapper is the right-aligning flex column; we leave it transparent
 * and style the inner bubble (which uses cpk:bg-muted, hence we also
 * target the substring class as a stable hook). */
.chat-css-demo-scope .copilotKitMessage.copilotKitUserMessage {
  background: transparent;
  padding: 0;
  border: none;
  box-shadow: none;
}

.chat-css-demo-scope
  .copilotKitMessage.copilotKitUserMessage
  > [class*="bg-muted"] {
  font-family: var(--halcyon-mono);
  font-size: 0.875rem;
  font-weight: 400;
  color: var(--halcyon-ink);
  background: var(--halcyon-paper-elevated);
  border: 1px solid var(--halcyon-rule);
  border-left: 2px solid var(--halcyon-ember);
  border-radius: 0;
  padding: 12px 16px 12px 18px;
  letter-spacing: -0.005em;
  line-height: 1.55;
  box-shadow: 0 1px 0 rgba(26, 23, 20, 0.03);
  position: relative;
}

/* A mono "→" marker before the user's text to read like a CLI prompt. */
.chat-css-demo-scope
  .copilotKitMessage.copilotKitUserMessage
  > [class*="bg-muted"]::before {
  content: "→";
  display: inline-block;
  margin-right: 10px;
  color: var(--halcyon-ember);
  font-weight: 500;
}

Reference

CSS ClassDescription
.copilotKitMessagesMain container for all chat messages
.copilotKitMessageBase class applied to every message bubble (user and assistant)
.copilotKitInputText input container with typing area and send button
.copilotKitUserMessageStyling for user messages
.copilotKitAssistantMessageStyling for AI responses
.copilotKitHeaderTop bar of chat window containing title and controls
.copilotKitButtonPrimary chat toggle button
.copilotKitWindowRoot container defining overall chat window dimensions
.copilotKitMarkdownStyles for rendered markdown content (v1 only)
.copilotKitCodeBlockCode snippet container with syntax highlighting (v1 only)
.copilotKitSidebarStyles for sidebar chat mode
.copilotKitPopupStyles for popup chat mode

Custom Fonts

You can customize the fonts by updating the font-family property on the relevant CopilotKit classes:

globals.css
.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?