Custom Styling

CopilotKit components are fully customizable through CSS variables, Tailwind CSS classes, and component slots. This guide covers all styling approaches to match your application’s design system.

Overview

CopilotKit uses a sophisticated styling system built on:

CSS Custom Properties - Theme variables prefixed with -- for colors, spacing, and borders
Tailwind CSS - Utility classes with cpk: prefix to avoid conflicts
Component Slots - Replace or extend component parts with custom implementations
Dark Mode - Built-in dark mode support with automatic theme switching

CSS Variables

All CopilotKit components use CSS variables defined on elements with the [data-copilotkit] attribute.

Color Variables

Override these variables to change the color scheme:

[data-copilotkit] {
  /* Background and foreground */
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  
  /* Card components */
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  
  /* Popovers and tooltips */
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  
  /* Primary actions */
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  
  /* Secondary elements */
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  
  /* Muted/disabled states */
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  
  /* Accent highlights */
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  
  /* Destructive actions */
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.577 0.245 27.325);
  
  /* Borders and inputs */
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  
  /* Border radius */
  --radius: 0.625rem;
}

Dark Mode Variables

Dark mode is automatically applied when the .dark class is present:

.dark [data-copilotkit],
[data-copilotkit].dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --border: oklch(0.269 0 0);
  /* ... other dark mode overrides ... */
}

Custom Theme Example

Create a custom theme with your brand colors:

/* Custom blue theme */
[data-copilotkit].theme-blue {
  --primary: oklch(0.5 0.2 250);        /* Blue */
  --primary-foreground: oklch(1 0 0);   /* White */
  --accent: oklch(0.7 0.15 270);        /* Light purple */
  --accent-foreground: oklch(0.1 0 0);  /* Dark */
  --border: oklch(0.8 0.05 250);        /* Light blue */
  --ring: oklch(0.5 0.2 250);           /* Blue focus ring */
}

/* Custom green theme */
[data-copilotkit].theme-green {
  --primary: oklch(0.5 0.15 150);       /* Green */
  --primary-foreground: oklch(1 0 0);   /* White */
  --accent: oklch(0.7 0.12 160);        /* Light green */
  --border: oklch(0.8 0.05 150);        /* Light green */
}

Apply themes in your React components:

<CopilotKitProvider className="theme-blue">
  <YourApp />
</CopilotKitProvider>

Tailwind CSS Classes

CopilotKit uses Tailwind CSS with a cpk: prefix to avoid conflicts with your application’s styles.

Using Utility Classes

Customize components by passing className props:

import { CopilotChat } from "@copilotkit/react";

function MyChat() {
  return (
    <CopilotChat 
      className="cpk:shadow-2xl cpk:border-2 cpk:border-primary"
    />
  );
}

Common Utility Patterns

// Spacing
className="cpk:p-4 cpk:m-2 cpk:space-y-4"

// Colors
className="cpk:bg-primary cpk:text-primary-foreground"

// Borders
className="cpk:border cpk:border-border cpk:rounded-lg"

// Typography
className="cpk:text-sm cpk:font-medium cpk:text-muted-foreground"

// Layout
className="cpk:flex cpk:items-center cpk:justify-between"

// Shadows
className="cpk:shadow-md cpk:shadow-primary/10"

Tailwind Configuration

CopilotKit’s Tailwind configuration includes theme tokens:

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-border: var(--border);
  /* ... more token mappings ... */
  
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}

Component Slots

Slots allow you to replace or customize specific parts of components.

String Slots (Class Names)

Pass a string to add CSS classes:

<CopilotChat 
  slots={{
    input: "cpk:bg-accent cpk:border-2",
    message: "cpk:p-4 cpk:rounded-xl"
  }}
/>

String slots are merged with existing classes using twMerge, so you can override default styles.

Object Slots (Props)

Pass an object to override component props:

<CopilotChat 
  slots={{
    input: {
      className: "custom-input",
      placeholder: "Ask me anything...",
      autoFocus: true
    }
  }}
/>

Component Slots (Custom Renderers)

Replace entire components with your own implementations:

<CopilotChat 
  slots={{
    message: ({ content, role }) => (
      <div className={`message message-${role}`}>
        <Avatar role={role} />
        <div className="message-content">{content}</div>
      </div>
    )
  }}
/>

Responsive Design

Control sidebar width with CSS variables:

/* Desktop - default 480px */
@media (min-width: 768px) {
  [data-copilot-sidebar] {
    width: var(--sidebar-width, 480px) !important;
  }
}

/* Mobile - full width */
@media (max-width: 767px) {
  [data-copilot-sidebar] {
    width: 100% !important;
  }
}

Set custom width in your component:

<CopilotSidebar 
  style={{ "--sidebar-width": "600px" } as React.CSSProperties}
/>

Mobile Optimizations

CopilotKit includes mobile-specific styles:

/* Better scrolling on iOS */
@media (max-width: 767px) {
  [data-copilot-sidebar] {
    -webkit-overflow-scrolling: touch;
  }
  
  [data-sidebar-chat] {
    touch-action: pan-y;
  }
}

/* Dynamic viewport height support */
@supports (height: 100dvh) {
  [data-copilot-sidebar] {
    height: 100dvh;
  }
}

Component-Specific Styling

Chat Messages

Style individual message components:

<CopilotChat 
  slots={{
    userMessage: "cpk:bg-primary cpk:text-primary-foreground cpk:rounded-2xl",
    assistantMessage: "cpk:bg-muted cpk:text-foreground cpk:border cpk:border-border",
    messageToolbar: "cpk:opacity-0 hover:cpk:opacity-100 cpk:transition-opacity"
  }}
/>

Input Field

Customize the chat input:

<CopilotChat 
  slots={{
    input: {
      className: "cpk:bg-background cpk:border-2 cpk:border-primary cpk:rounded-full cpk:px-6",
      placeholder: "Type your message..."
    }
  }}
/>

Audio Recorder

The audio recorder uses canvas for visualization:

// Custom canvas styling
const recorderClassName = "cpk:h-11 cpk:w-full cpk:px-5";

<CopilotChatAudioRecorder 
  inputClass={recorderClassName}
/>

Customize the waveform colors:

[data-copilotkit] canvas.audio-visualizer {
  /* Canvas inherits color from CSS */
  color: var(--primary);
}

Advanced Customization

Custom Animations

Define custom animations with Tailwind:

@theme {
  --animate-pulse-cursor: pulse-cursor 0.9s cubic-bezier(0.4, 0, 0.2, 1) infinite;
  
  @keyframes pulse-cursor {
    0%, 100% {
      transform: scale(1);
      opacity: 1;
    }
    50% {
      transform: scale(1.5);
      opacity: 0.8;
    }
  }
}

Use in components:

<div className="cpk:animate-pulse-cursor">●</div>

Custom Component Example

Build a fully custom message component:

function CustomMessage({ message }: { message: Message }) {
  const isUser = message.role === "user";
  
  return (
    <div 
      className={`
        cpk:flex cpk:gap-3 cpk:p-4 cpk:rounded-lg cpk:mb-2
        ${isUser 
          ? "cpk:bg-primary cpk:text-primary-foreground cpk:ml-auto cpk:max-w-[80%]" 
          : "cpk:bg-card cpk:border cpk:border-border"
        }
      `}
    >
      {!isUser && (
        <img 
          src="/bot-avatar.png" 
          className="cpk:w-8 cpk:h-8 cpk:rounded-full" 
          alt="Assistant"
        />
      )}
      
      <div className="cpk:flex-1">
        <div className="cpk:text-sm cpk:font-medium cpk:mb-1">
          {isUser ? "You" : "Assistant"}
        </div>
        <div className="cpk:text-sm">
          {message.content}
        </div>
      </div>
      
      {isUser && (
        <img 
          src="/user-avatar.png" 
          className="cpk:w-8 cpk:h-8 cpk:rounded-full" 
          alt="You"
        />
      )}
    </div>
  );
}

// Use in CopilotChat
<CopilotChat 
  slots={{
    message: CustomMessage
  }}
/>

Theming Best Practices

Use CSS Variables

Prefer CSS variables for theme-able values to enable easy theme switching

Maintain Contrast

Ensure sufficient contrast between foreground and background colors for accessibility

Test Dark Mode

Always test your custom themes in both light and dark modes

Namespace Carefully

Use the cpk: prefix for all Tailwind utilities to avoid style conflicts

Debugging Styles

Inspect CSS Variables

Check applied CSS variables in browser DevTools:

// Get computed styles
const element = document.querySelector('[data-copilotkit]');
const styles = getComputedStyle(element);
const primaryColor = styles.getPropertyValue('--primary');
console.log('Primary color:', primaryColor);

Override Detection

Check if your overrides are applied:

/* Add !important temporarily for debugging */
[data-copilotkit].debug {
  --primary: red !important;
}

Example: Complete Custom Theme

Here’s a complete example combining all styling approaches:

// theme.css
[data-copilotkit].custom-theme {
  /* Brand colors */
  --primary: oklch(0.45 0.25 250);
  --primary-foreground: oklch(1 0 0);
  --secondary: oklch(0.75 0.15 250);
  --accent: oklch(0.85 0.1 270);
  
  /* Rounded corners */
  --radius: 1rem;
  
  /* Custom shadows */
  --shadow-color: 250 100% 50%;
}

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

function App() {
  return (
    <CopilotKitProvider className="custom-theme">
      <CopilotChat 
        className="cpk:shadow-2xl"
        slots={{
          input: {
            className: "cpk:rounded-full cpk:border-2 cpk:border-primary",
            placeholder: "Ask anything..."
          },
          userMessage: "cpk:bg-primary cpk:text-primary-foreground cpk:rounded-2xl cpk:shadow-lg",
          assistantMessage: "cpk:bg-secondary/20 cpk:border cpk:border-secondary cpk:rounded-2xl"
        }}
      />
    </CopilotKitProvider>
  );
}

Component Reference

View all available components and their slot options

Tailwind CSS Docs

Learn more about Tailwind CSS utilities

​Custom Styling

​Overview

​CSS Variables

​Color Variables

​Dark Mode Variables

​Custom Theme Example

​Tailwind CSS Classes

​Using Utility Classes

​Common Utility Patterns

​Tailwind Configuration

​Component Slots

​String Slots (Class Names)

​Object Slots (Props)

​Component Slots (Custom Renderers)

​Responsive Design

​Sidebar Width

​Mobile Optimizations

​Component-Specific Styling

​Chat Messages

​Input Field

​Audio Recorder

​Advanced Customization

​Custom Animations

​Custom Component Example

​Theming Best Practices