# CSS Customization

> Theme CopilotKit components via CSS variables and class overrides.

<!-- interactive demo: chat-customization-css -->

## What is this? [#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](/agno/custom-look-and-feel/slots) or
[fully headless UI](/agno/custom-look-and-feel/headless-ui).

## Scoping the theme [#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:

```typescript title="src/app/demos/chat-customization-css/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) [#css-variables-easiest]

The v2 components that the demo uses read the shadcn tokens listed in
[v2 design tokens](#v2-design-tokens-shadcn). The demo overrides these tokens
on the `[data-copilotkit]` element inside its scope wrapper:

```css title="src/app/demos/chat-customization-css/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:

```tsx
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:

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

### Reference [#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 |

<Callout type="info" title="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](#v2-design-tokens-shadcn) below.
</Callout>

## v2 Design Tokens (shadcn) [#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](https://oklch.com) 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:

```css title="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 [#reference-1]

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 |

<Callout type="info" title="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.
</Callout>

## Custom CSS [#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:

```css title="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:

```css title="src/app/demos/chat-customization-css/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 [#reference-2]

| 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 [#custom-fonts]

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

```css title="globals.css"
.copilotKitMessages {
  font-family: Arial, sans-serif;
}

.copilotKitInput {
  font-family: Arial, sans-serif;
}
```

## Custom Icons [#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](/agno/custom-look-and-feel/slots).

```tsx
<CopilotChat
  icons={{
    openIcon: <YourOpenIconComponent />,
    closeIcon: <YourCloseIconComponent />,
  }}
/>
```

## Custom Labels [#custom-labels]

Customize all user-facing copy via the `labels` prop:

```tsx
<CopilotChat
  labels={{
    welcomeMessageText: "Hello! How can I help you today?",
    modalHeaderTitle: "My Copilot",
    chatInputPlaceholder: "Ask me anything!",
  }}
/>
```
