Customizations

Extend the SDK's UI with custom themes, CSS overrides, and branding options.

For base setup and pre-built themes, see UI Components.

CSS Variables Reference

The SDK uses standard shadcn/ui CSS variables. Override these to customize the look:

:root {
  /* Background colors */
  --background: hsl(0 0% 100%);
  --foreground: hsl(0 0% 0%);

  /* Card/panel colors */
  --card: hsl(0 0% 100%);
  --card-foreground: hsl(0 0% 0%);

  /* Primary action color */
  --primary: hsl(220 90% 50%);
  --primary-foreground: hsl(0 0% 100%);

  /* Secondary elements */
  --secondary: hsl(220 10% 95%);
  --secondary-foreground: hsl(0 0% 0%);

  /* Muted/subtle elements */
  --muted: hsl(220 10% 95%);
  --muted-foreground: hsl(0 0% 45%);

  /* Accent highlights */
  --accent: hsl(220 10% 95%);
  --accent-foreground: hsl(0 0% 0%);

  /* Destructive actions */
  --destructive: hsl(0 84% 60%);
  --destructive-foreground: hsl(0 0% 100%);

  /* Borders and inputs */
  --border: hsl(220 10% 90%);
  --input: hsl(220 10% 90%);
  --ring: hsl(220 90% 50%);

  /* Border radius */
  --radius: 0.5rem;
}

.dark {
  --background: hsl(0 0% 5%);
  --foreground: hsl(0 0% 95%);
  /* ... dark mode overrides */
}

Semantic CSS Classes

Target specific components with these CSS classes:

Message Components

Class	Element
`csdk-message`	Message container
`csdk-message-user`	User message bubble
`csdk-message-assistant`	Assistant message bubble
`csdk-message-content`	Message text content
`csdk-avatar`	Avatar container

Input Components

Class	Element
`csdk-input`	Input container
`csdk-input-textarea`	Text input field
`csdk-button`	All buttons
`csdk-button-send`	Send button
`csdk-button-stop`	Stop generation button
`csdk-button-attach`	Attachment button

Layout Components

Class	Element
`csdk-chat-header`	Header slot
`csdk-chat-footer`	Footer slot
`csdk-chat-home-view`	Home view container
`csdk-chat-view`	Chat view container
`csdk-back-button`	Back/New chat button

Other Components

Class	Element
`csdk-followup`	Follow-up suggestions container
`csdk-followup-button`	Follow-up suggestion buttons
`csdk-compound-input`	Compound input wrapper
`csdk-compound-suggestions`	Compound suggestions wrapper

Creating Custom Themes

1. Create Theme File

themes/my-brand.css

.csdk-theme-mybrand,
[data-csdk-theme="mybrand"] {
  /* Colors */
  --background: hsl(210 20% 98%);
  --foreground: hsl(210 40% 10%);
  --primary: hsl(210 100% 50%);
  --primary-foreground: hsl(0 0% 100%);
  --secondary: hsl(210 20% 94%);
  --secondary-foreground: hsl(210 40% 10%);
  --muted: hsl(210 20% 94%);
  --muted-foreground: hsl(210 20% 40%);
  --accent: hsl(210 100% 95%);
  --accent-foreground: hsl(210 100% 40%);
  --border: hsl(210 20% 88%);
  --input: hsl(210 20% 88%);
  --ring: hsl(210 100% 50%);

  /* Border radius */
  --radius: 0.75rem;
}

/* Dark mode variant */
.dark.csdk-theme-mybrand,
.dark .csdk-theme-mybrand {
  --background: hsl(210 30% 8%);
  --foreground: hsl(210 20% 95%);
  --primary: hsl(210 100% 60%);
  /* ... */
}

2. Add Component Overrides

themes/my-brand.css

/* Custom message styling */
.csdk-theme-mybrand .csdk-message-user {
  border: 2px solid var(--primary);
  box-shadow: 4px 4px 0 0 var(--primary);
}

/* Rounded send button */
.csdk-theme-mybrand .csdk-button-send {
  border-radius: 50%;
}

/* Custom input styling */
.csdk-theme-mybrand .csdk-input-textarea {
  border-width: 2px;
}

3. Apply Theme

import "./themes/my-brand.css";
import { CopilotChat } from "@yourgpt/copilot-sdk/ui";

<div className="csdk-theme-mybrand">
  <CopilotChat />
</div>

Branding

<CopilotChat
  header={{
    title: 'Support Assistant',
    subtitle: 'How can I help you today?',
    logo: '/logo.svg',
  }}
/>

Welcome Message

<CopilotChat
  welcomeMessage="Hi! I'm your AI assistant. Ask me anything about our products."
/>

Placeholder

<CopilotChat
  placeholder="Type your question here..."
/>

Avatars

<CopilotChat
  userAvatar="/user-avatar.png"
  assistantAvatar="/ai-avatar.png"
/>

Layout Options

Position

// Floating button (default)
<CopilotChat position="bottom-right" />

// Embedded in page
<CopilotChat embedded={true} />

// Full page
<CopilotChat fullPage={true} />

Size

<CopilotChat
  width={400}
  height={600}
  maxHeight="80vh"
/>

Input Options

Attachments

<CopilotChat
  attachmentsEnabled={true}
  allowedFileTypes={['image/*', '.pdf', '.doc']}
  maxFileSize={10 * 1024 * 1024} // 10MB
/>

Voice Input

<CopilotChat
  voiceEnabled={true}
/>

Behavior

Auto-focus

<CopilotChat
  autoFocus={true}
/>

Persist History

<CopilotChat
  persistHistory={true}
  storageKey="my-app-chat"
/>

Scroll Behavior

<CopilotChat
  scrollBehavior="smooth" // 'smooth' | 'instant' | 'auto'
/>

Custom Message Rendering

<CopilotChat
  renderMessage={(message) => (
    <div className="custom-message">
      <Markdown>{message.content}</Markdown>
    </div>
  )}
/>

Full Example

import "./themes/my-brand.css";
import { CopilotChat } from "@yourgpt/copilot-sdk/ui";

<div className="csdk-theme-mybrand">
  <CopilotChat
    // Branding
    header={{
      title: 'AI Assistant',
      logo: '/logo.svg',
    }}
    welcomeMessage="How can I help you today?"
    placeholder="Ask anything..."

    // Layout
    position="bottom-right"
    width={400}

    // Features
    attachmentsEnabled={true}
    voiceEnabled={true}
    persistHistory={true}

    // Avatars
    userAvatar="/user.png"
    assistantAvatar="/ai.png"
  />
</div>

Next Steps

UI Components - Pre-built components and themes
Generative UI - Render custom components from AI
Chat - Full chat component API

Customizations

On this page