Styling Reference

The chat widget can be customized using style props, CSS variables, or class names.

Style Props

Pass a styles object to configure the widget appearance programmatically.

<ChatWidget
  styles={{
    theme: 'auto',
    primaryColor: '#3b82f6',
    // ... other options
  }}
/>

Available Style Props

Property	Type	Default	Description
`theme`	`'auto' \| 'light' \| 'dark'`	`'auto'`	Theme mode. `auto` follows the host app or system preference
`primaryColor`	`string`	`#3b82f6`	Primary brand color (header, buttons, user bubbles)
`primaryTextColor`	`string`	`#ffffff`	Text color on primary-colored elements
`backgroundColor`	`string`	`#ffffff`	Main background color
`borderColor`	`string`	`#e5e7eb`	Border color for container and inputs
`headerTextColor`	`string`	`#ffffff`	Header title text color
`userBubbleTextColor`	`string`	`#ffffff`	Text color in user message bubbles
`assistantBubbleBackground`	`string`	`transparent`	Background for assistant message bubbles
`assistantBubbleTextColor`	`string`	`#111827`	Text color in assistant message bubbles
`fontFamily`	`string`	`'Inter', system-ui, sans-serif`	Font family for all text
`borderRadius`	`string`	`0.75rem`	Border radius for container and bubbles
`inputBackground`	`string`	`#ffffff`	Background color for input area
`inputTextColor`	`string`	`#111827`	Text color in input field
`inputPlaceholderColor`	`string`	`#6b7280`	Placeholder text color
`thoughtsBorderColor`	`string`	`#d1d5db`	Border color for expandable thoughts section

Light and Dark Mode

By default, the widget uses:

styles={{ theme: 'auto' }}

In auto mode, the widget detects the host page theme in this order:

data-theme="dark" or data-theme="light" on <html> or <body>
.dark or .light class on <html> or <body>
CSS color-scheme
the user's prefers-color-scheme system setting

You can force a specific mode:

<ChatWidget
  styles={{ theme: 'dark' }}
/>

<ChatWidget
  styles={{ theme: 'light' }}
/>

Theme mode chooses the built-in light or dark color set. Any other values in styles override the selected theme, so you can use automatic dark mode and still customize brand colors:

<ChatWidget
  styles={{
    theme: 'auto',
    primaryColor: '#6366f1',
    borderRadius: '1rem',
  }}
/>

Example: Full Configuration

<ChatWidget
  styles={{
    theme: 'auto',

    // Brand colors
    primaryColor: '#6366f1',
    primaryTextColor: '#ffffff',

    // Container
    backgroundColor: '#ffffff',
    borderColor: '#e5e7eb',
    borderRadius: '1rem',

    // Header
    headerTextColor: '#ffffff',

    // Messages
    userBubbleTextColor: '#ffffff',
    assistantBubbleBackground: '#f3f4f6',
    assistantBubbleTextColor: '#111827',

    // Input
    inputBackground: '#ffffff',
    inputTextColor: '#111827',
    inputPlaceholderColor: '#9ca3af',

    // Typography
    fontFamily: "'Roboto', system-ui, sans-serif",

    // Other
    thoughtsBorderColor: '#e5e7eb',
  }}
/>

CSS Variables

Override styles globally using CSS custom properties on [data-chat-widget].

Core Variables

Variable	Default	Description
`--chat-primary`	`#3b82f6`	Primary brand color
`--chat-primary-text`	`#ffffff`	Text on primary color
`--chat-primary-hover`	`#2563eb`	Hover state for primary (auto-generated)
`--chat-background`	`#ffffff`	Main background
`--chat-border`	`#e5e7eb`	Border color

Typography Variables

Variable	Default	Description
`--chat-font-family`	`'Inter', system-ui, ...`	Font family
`--chat-font-size`	`0.925rem`	Base font size for messages
`--chat-thought-font-size`	`0.75rem`	Font size for thoughts section
`--chat-radius`	`0.75rem`	Base border radius

Message Variables

Variable	Default	Description
`--chat-header-text`	`#ffffff`	Header title color
`--chat-user-text`	`#ffffff`	User bubble text color
`--chat-assistant-bg`	`transparent`	Assistant bubble background
`--chat-assistant-text`	`#111827`	Assistant bubble text color
`--chat-thought-border`	`#d1d5db`	Thoughts section border

Input Variables

Variable	Default	Description
`--chat-input-bg`	`#ffffff`	Input area background
`--chat-input-text`	`#111827`	Input text color
`--chat-input-placeholder`	`#6b7280`	Placeholder color

Example: CSS Variable Override

[data-chat-widget] {
  --chat-primary: #8b5cf6;
  --chat-primary-hover: #7c3aed;
  --chat-background: #fafafa;
  --chat-border: #e5e7eb;
  --chat-font-family: 'Poppins', sans-serif;
  --chat-radius: 1rem;

  /* Messages */
  --chat-assistant-bg: #f3f4f6;
  --chat-assistant-text: #1f2937;

  /* Input */
  --chat-input-bg: #ffffff;
  --chat-input-text: #1f2937;
}

CSS Class Names

BEM-style class names for targeted CSS customization.

Container Classes

Class	Description
`.chat-widget`	Root container
`.chat-widget__header`	Header bar
`.chat-widget__title`	Header title text
`.chat-widget__messages`	Scrollable message area

Message Classes

Class	Description
`.chat-widget__message`	Message wrapper
`.chat-widget__message-row`	Message row container
`.chat-widget__message-row--user`	User message row (right-aligned)
`.chat-widget__message-row--assistant`	Assistant message row (left-aligned)
`.chat-widget__bubble`	Message bubble base
`.chat-widget__bubble--user`	User message bubble
`.chat-widget__bubble--assistant`	Assistant message bubble
`.chat-widget__markdown`	Markdown content wrapper
`.chat-widget__widget`	Custom widget container

Thoughts Section Classes

Class	Description
`.chat-widget__thoughts`	Thoughts container
`.chat-widget__details`	Expandable details element
`.chat-widget__thoughts-summary`	Clickable summary row
`.chat-widget__thoughts-icon-container`	Icon wrapper
`.chat-widget__thoughts-icon`	Chevron icon
`.chat-widget__thoughts-content`	Expanded content area
`.chat-widget__thoughts-text`	Thoughts text (monospace)

Input Classes

Class	Description
`.chat-widget__input`	Input container
`.chat-widget__form`	Form wrapper
`.chat-widget__textarea`	Text input field
`.chat-widget__toolbar`	Toolbar area (mic button, etc.)
`.chat-widget__submit`	Send button
`.chat-widget__send-icon`	Send button icon

Voice Classes

Class	Description
`.chat-widget__mic-button`	Microphone button
`.chat-widget__mic-button--active`	Active recording state
`.chat-widget__mic-icon`	Microphone icon
`.chat-widget__mic-bar`	Volume indicator bar
`.chat-widget__mic-bar-fill`	Volume level fill
`.chat-widget__voice`	Voice playback container
`.chat-widget__voice-button`	Play voice button
`.chat-widget__voice-button--active`	Playing state
`.chat-widget__voice-icon`	Voice icon
`.chat-widget__voice-icon--spin`	Loading spinner state

Feedback Classes

Class	Description
`.chat-widget__feedback`	Feedback buttons container
`.chat-widget__feedback-button`	Feedback button base
`.chat-widget__feedback-button--positive`	Thumbs up button
`.chat-widget__feedback-button--negative`	Thumbs down button
`.chat-widget__feedback-button--comment`	Comment button
`.chat-widget__feedback-button--selected`	Selected state
`.chat-widget__feedback-button--has-content`	Has comment state
`.chat-widget__feedback-icon`	Feedback icon
`.chat-widget__feedback-comment-section`	Comment input section
`.chat-widget__feedback-textarea`	Comment textarea
`.chat-widget__feedback-submit`	Submit comment button
`.chat-widget__feedback-cancel`	Cancel button

Loading Classes

Class	Description
`.chat-widget__loading`	Loading indicator container
`.chat-widget__loading-bubble`	Loading bubble
`.chat-widget__loading-dots`	Dots container
`.chat-widget__loading-dot`	Individual dot (animated)

Collapsed Content Classes

Class	Description
`.chat-widget__collapsed`	Collapsed content wrapper
`.chat-widget__collapsed-content`	Expandable content (CSS grid)
`.chat-widget__collapsed-content--expanded`	Expanded state
`.chat-widget__collapsed-preview`	Preview when collapsed
`.chat-widget__collapsed-gradient`	Fade gradient overlay
`.chat-widget__collapsed-toggle`	Expand/collapse button

Class	Description
`.chat-popup__anchor`	Anchor button container
`.chat-popup--start`	Left-aligned variant
`.chat-popup__anchor-button`	Floating action button
`.chat-popup__anchor-icon`	Button icon
`.chat-popup__panel`	Popup panel container
`.chat-popup__panel--open`	Open state
`.chat-popup__panel--closed`	Closed state
`.chat-popup__panel-inner`	Inner panel wrapper
`.chat-popup__close`	Close button container
`.chat-popup__close-button`	Close button
`.chat-popup__close-icon`	Close icon

Theme Examples

Dark Mode

<ChatWidget
  styles={{
    primaryColor: '#6366f1',
    backgroundColor: '#1f2937',
    borderColor: '#374151',
    assistantBubbleBackground: '#374151',
    assistantBubbleTextColor: '#f9fafb',
    inputBackground: '#374151',
    inputTextColor: '#f9fafb',
    inputPlaceholderColor: '#9ca3af',
    thoughtsBorderColor: '#4b5563',
  }}
/>

Or using CSS variables:

[data-chat-widget] {
  --chat-primary: #6366f1;
  --chat-background: #1f2937;
  --chat-border: #374151;
  --chat-assistant-bg: #374151;
  --chat-assistant-text: #f9fafb;
  --chat-input-bg: #374151;
  --chat-input-text: #f9fafb;
  --chat-input-placeholder: #9ca3af;
  --chat-thought-border: #4b5563;
}

Minimal / Borderless

[data-chat-widget] {
  --chat-border: transparent;
  --chat-radius: 0.5rem;
  --chat-assistant-bg: transparent;
}

.chat-widget {
  box-shadow: none;
  border: none;
}

.chat-widget__bubble--user {
  border-radius: 1rem;
}

Custom Font Sizing

[data-chat-widget] {
  --chat-font-size: 1rem;
  --chat-thought-font-size: 0.875rem;
}

.chat-widget__title {
  font-size: 1rem;
}

.chat-widget__textarea {
  font-size: 1rem;
}

Styling Reference

On this page