Theming & Customization

Learn how to customize the appearance of the Cyborg chat widget to match your brand.

Overview

The Cyborg SDK provides multiple levels of customization:

Theme Configuration - Colors, fonts, and spacing
Position Options - Widget placement
CSS Variables - Fine-grained style control
Custom Components - Full UI replacement

Theme Configuration

Pass theme options to the CyborgProvider config:

tsx

import { CyborgProvider } from '@cyborg-sdk/react'

function App() {
  return (
    <CyborgProvider
      config={{
        publishableKey: process.env.CYBORG_PUBLISHABLE_KEY,
        theme: {
          primaryColor: '#6366f1',
          fontFamily: 'Inter, sans-serif'
        }
      }}
    >
      <YourApp />
    </CyborgProvider>
  )
}

Theme Options

Option	Type	Default	Description
`primaryColor`	`string`	`#6366f1`	Main accent color
`backgroundColor`	`string`	`#ffffff`	Chat window background
`textColor`	`string`	`#1f2937`	Primary text color
`fontFamily`	`string`	`system-ui`	Font family
`borderRadius`	`string`	`12px`	Corner rounding
`position`	`string`	`bottom-right`	Widget position

Color Customization

Brand Colors

Match your brand's primary color:

tsx

theme: {
  primaryColor: '#your-brand-color',
  // Auto-generates complementary colors for:
  // - Button backgrounds
  // - Links
  // - User message bubbles
  // - Focus states
}

Dark Mode

Create a dark theme:

tsx

theme: {
  primaryColor: '#818cf8',
  backgroundColor: '#1f2937',
  textColor: '#f9fafb'
}

Light Mode

Create a light theme (default):

tsx

theme: {
  primaryColor: '#6366f1',
  backgroundColor: '#ffffff',
  textColor: '#1f2937'
}

Position Options

Control where the chat widget appears:

tsx

theme: {
  position: 'bottom-right' // default
}

Available positions:

bottom-right - Lower right corner
bottom-left - Lower left corner
top-right - Upper right corner
top-left - Upper left corner

Typography

Customize fonts to match your design system:

tsx

theme: {
  fontFamily: 'Inter, system-ui, sans-serif'
}

Using Custom Fonts

Ensure your font is loaded before using it:

tsx

// In your CSS or HTML
import '@fontsource/inter'

// In your config
theme: {
  fontFamily: 'Inter, sans-serif'
}

Border Radius

Adjust corner rounding:

tsx

// Rounded (default)
theme: { borderRadius: '12px' }

// More rounded
theme: { borderRadius: '20px' }

// Sharp corners
theme: { borderRadius: '4px' }

// Fully rounded
theme: { borderRadius: '9999px' }

CSS Variables

For fine-grained control, override CSS variables:

css

:root {
  /* Colors */
  --cyborg-primary: #6366f1;
  --cyborg-primary-hover: #4f46e5;
  --cyborg-background: #ffffff;
  --cyborg-surface: #f9fafb;
  --cyborg-text: #1f2937;
  --cyborg-text-secondary: #6b7280;
  --cyborg-border: #e5e7eb;

  /* Typography */
  --cyborg-font-family: system-ui, sans-serif;
  --cyborg-font-size-sm: 0.875rem;
  --cyborg-font-size-base: 1rem;
  --cyborg-font-size-lg: 1.125rem;

  /* Spacing */
  --cyborg-spacing-xs: 0.25rem;
  --cyborg-spacing-sm: 0.5rem;
  --cyborg-spacing-md: 1rem;
  --cyborg-spacing-lg: 1.5rem;

  /* Layout */
  --cyborg-border-radius: 12px;
  --cyborg-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  --cyborg-widget-width: 400px;
  --cyborg-widget-height: 600px;
}

Dark Mode CSS Variables

css

[data-theme='dark'] {
  --cyborg-primary: #818cf8;
  --cyborg-background: #1f2937;
  --cyborg-surface: #374151;
  --cyborg-text: #f9fafb;
  --cyborg-text-secondary: #9ca3af;
  --cyborg-border: #4b5563;
}

Complete Theme Examples

Minimal Light

tsx

<CyborgProvider
  config={{
    publishableKey: process.env.CYBORG_PUBLISHABLE_KEY,
    theme: {
      primaryColor: '#000000',
      backgroundColor: '#ffffff',
      textColor: '#000000',
      fontFamily: 'system-ui, sans-serif',
      borderRadius: '8px'
    }
  }}
>

Vibrant Brand

tsx

<CyborgProvider
  config={{
    publishableKey: process.env.CYBORG_PUBLISHABLE_KEY,
    theme: {
      primaryColor: '#ec4899',
      backgroundColor: '#fdf2f8',
      textColor: '#831843',
      fontFamily: 'Poppins, sans-serif',
      borderRadius: '16px'
    }
  }}
>

Corporate Dark

tsx

<CyborgProvider
  config={{
    publishableKey: process.env.CYBORG_PUBLISHABLE_KEY,
    theme: {
      primaryColor: '#3b82f6',
      backgroundColor: '#0f172a',
      textColor: '#e2e8f0',
      fontFamily: 'Inter, sans-serif',
      borderRadius: '4px'
    }
  }}
>

Responsive Behavior

The chat widget automatically adapts to screen size:

Desktop: Floating widget in configured position
Mobile: Full-screen overlay when open
Tablet: Responsive sizing based on viewport

Custom Breakpoints

Override responsive behavior with CSS:

css

/* Custom mobile breakpoint */
@media (max-width: 640px) {
  .cyborg-widget {
    --cyborg-widget-width: 100%;
    --cyborg-widget-height: 100%;
  }
}

/* Custom widget size on large screens */
@media (min-width: 1280px) {
  .cyborg-widget {
    --cyborg-widget-width: 480px;
    --cyborg-widget-height: 700px;
  }
}

Suggested Prompts Styling

Customize the appearance of suggested prompt buttons:

css

.cyborg-suggested-prompt {
  background: var(--cyborg-surface);
  border: 1px solid var(--cyborg-border);
  border-radius: var(--cyborg-border-radius);
  color: var(--cyborg-text);
  padding: var(--cyborg-spacing-sm) var(--cyborg-spacing-md);
}

.cyborg-suggested-prompt:hover {
  background: var(--cyborg-primary);
  color: white;
}

Animation Customization

Control chat widget animations:

css

/* Slower open animation */
.cyborg-widget {
  --cyborg-animation-duration: 300ms;
}

/* Disable animations */
.cyborg-widget {
  --cyborg-animation-duration: 0ms;
}

/* Custom easing */
.cyborg-widget {
  --cyborg-animation-easing: cubic-bezier(0.4, 0, 0.2, 1);
}

Z-Index Control

Ensure the widget appears above your content:

css

.cyborg-widget {
  --cyborg-z-index: 9999;
}

Best Practices

1. Test Contrast

Ensure text is readable against backgrounds:

tsx

// Good contrast
theme: {
  backgroundColor: '#1f2937',
  textColor: '#f9fafb' // Light text on dark bg
}

// Bad contrast
theme: {
  backgroundColor: '#e5e7eb',
  textColor: '#9ca3af' // Low contrast
}

2. Match Your Design System

Use your existing design tokens:

tsx

import { tokens } from './design-system'

theme: {
  primaryColor: tokens.colors.primary,
  fontFamily: tokens.fonts.body,
  borderRadius: tokens.radii.lg
}

3. Consider Accessibility

Maintain sufficient color contrast (WCAG AA: 4.5:1)
Don't rely on color alone to convey information
Ensure focus states are visible

4. Test on Multiple Devices

Verify your theme works across:

Desktop browsers
Mobile Safari and Chrome
Tablet viewports
Light and dark system preferences

Next Steps

CyborgProvider - Full configuration options
Context-Aware Chat - Dynamic context
Tool Calling - Custom actions

Theming & Customization ​

Overview ​

Theme Configuration ​

Theme Options ​

Color Customization ​

Brand Colors ​

Dark Mode ​

Light Mode ​

Position Options ​

Typography ​

Using Custom Fonts ​

Border Radius ​

CSS Variables ​

Dark Mode CSS Variables ​

Complete Theme Examples ​

Minimal Light ​

Vibrant Brand ​

Corporate Dark ​

Responsive Behavior ​

Custom Breakpoints ​

Suggested Prompts Styling ​

Animation Customization ​

Z-Index Control ​

Best Practices ​

1. Test Contrast ​

2. Match Your Design System ​

3. Consider Accessibility ​

4. Test on Multiple Devices ​

Next Steps ​