Styling Guide

Advanced customization and styling options for the Koi Widget to perfectly match your brand and design requirements.

CSS Classes Reference

The Koi Widget uses a consistent class naming convention for easy styling:

Main Container

1.koi-widget-container {
2  /* Main widget container */
3}
4
5.koi-widget-overlay {
6  /* Background overlay when widget is open */
7}
8

Chat Button

1.koi-widget-button {
2  /* The floating chat button */
3}
4
5.koi-widget-button:hover {
6  /* Button hover state */
7}
8
9.koi-widget-button.open {
10  /* Button when chat is open */
11}
12
13.koi-widget-button-icon {
14  /* Icon inside the button */
15}
16

Chat Interface

1.koi-widget-chat {
2  /* Main chat interface container */
3}
4
5.koi-widget-header {
6  /* Chat header with title and controls */
7}
8
9.koi-widget-title {
10  /* Chat title text */
11}
12
13.koi-widget-close {
14  /* Close button in header */
15}
16
17.koi-widget-minimize {
18  /* Minimize button in header */
19}
20

Messages

1.koi-widget-messages {
2  /* Messages container */
3}
4
5.koi-widget-message {
6  /* Individual message bubble */
7}
8
9.koi-widget-message.user {
10  /* User messages */
11}
12
13.koi-widget-message.bot {
14  /* Bot/AI messages */
15}
16
17.koi-widget-message.system {
18  /* System messages */
19}
20
21.koi-widget-message-content {
22  /* Message text content */
23}
24
25.koi-widget-message-time {
26  /* Message timestamp */
27}
28
29.koi-widget-message-avatar {
30  /* Message sender avatar */
31}
32

Input Area

1.koi-widget-input-container {
2  /* Input area container */
3}
4
5.koi-widget-input {
6  /* Text input field */
7}
8
9.koi-widget-send-button {
10  /* Send message button */
11}
12
13.koi-widget-file-button {
14  /* File upload button */
15}
16
17.koi-widget-emoji-button {
18  /* Emoji picker button */
19}
20

Quick Actions

1.koi-widget-quick-actions {
2  /* Quick actions container */
3}
4
5.koi-widget-quick-action {
6  /* Individual quick action button */
7}
8
9.koi-widget-quick-action:hover {
10  /* Quick action hover state */
11}
12

Custom Styling Examples

Modern Gradient Theme

1window.KoiWidgetConfig = {
2  primaryColor: '#667eea',
3  accentColor: '#764ba2',
4  customCSS: `
5    .koi-widget-button {
6      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
7      border-radius: 50% !important;
8      box-shadow: 0 8px 32px rgba(102, 126, 234, 0.3) !important;
9      transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1) !important;
10    }
11    
12    .koi-widget-button:hover {
13      transform: scale(1.1) translateY(-2px) !important;
14      box-shadow: 0 12px 40px rgba(102, 126, 234, 0.4) !important;
15    }
16    
17    .koi-widget-header {
18      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
19      border-radius: 20px 20px 0 0 !important;
20    }
21    
22    .koi-widget-message.user {
23      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
24      border-radius: 20px 20px 5px 20px !important;
25      color: white !important;
26    }
27    
28    .koi-widget-message.bot {
29      background: linear-gradient(135deg, #f7fafc 0%, #edf2f7 100%) !important;
30      border-radius: 20px 20px 20px 5px !important;
31      border: 1px solid #e2e8f0 !important;
32    }
33  `
34};
35

Minimalist Theme

1window.KoiWidgetConfig = {
2  primaryColor: '#000000',
3  accentColor: '#333333',
4  backgroundColor: '#ffffff',
5  customCSS: `
6    .koi-widget-button {
7      background: #000000 !important;
8      border-radius: 8px !important;
9      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1) !important;
10      transition: all 0.2s ease !important;
11    }
12    
13    .koi-widget-button:hover {
14      background: #333333 !important;
15      transform: translateY(-1px) !important;
16    }
17    
18    .koi-widget-header {
19      background: #000000 !important;
20      border-radius: 0 !important;
21      border-bottom: 1px solid #e5e5e5 !important;
22    }
23    
24    .koi-widget-chat {
25      border-radius: 0 !important;
26      box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1) !important;
27    }
28    
29    .koi-widget-message.user {
30      background: #000000 !important;
31      border-radius: 4px !important;
32      color: white !important;
33    }
34    
35    .koi-widget-message.bot {
36      background: #f5f5f5 !important;
37      border-radius: 4px !important;
38      border: none !important;
39    }
40    
41    .koi-widget-input {
42      border-radius: 4px !important;
43      border: 1px solid #e5e5e5 !important;
44    }
45    
46    .koi-widget-quick-action {
47      border-radius: 4px !important;
48      border: 1px solid #e5e5e5 !important;
49      background: white !important;
50    }
51  `
52};
53

Rounded Bubble Theme

1window.KoiWidgetConfig = {
2  primaryColor: '#ff6b6b',
3  accentColor: '#4ecdc4',
4  customCSS: `
5    .koi-widget-button {
6      background: #ff6b6b !important;
7      border-radius: 50% !important;
8      box-shadow: 0 6px 20px rgba(255, 107, 107, 0.3) !important;
9      transition: all 0.3s ease !important;
10    }
11    
12    .koi-widget-button:hover {
13      transform: scale(1.15) !important;
14      box-shadow: 0 8px 25px rgba(255, 107, 107, 0.4) !important;
15    }
16    
17    .koi-widget-chat {
18      border-radius: 25px !important;
19      overflow: hidden !important;
20    }
21    
22    .koi-widget-header {
23      background: #ff6b6b !important;
24      border-radius: 25px 25px 0 0 !important;
25    }
26    
27    .koi-widget-message.user {
28      background: #ff6b6b !important;
29      border-radius: 25px 25px 8px 25px !important;
30      color: white !important;
31    }
32    
33    .koi-widget-message.bot {
34      background: #4ecdc4 !important;
35      border-radius: 25px 25px 25px 8px !important;
36      color: white !important;
37    }
38    
39    .koi-widget-input {
40      border-radius: 25px !important;
41      border: 2px solid #ff6b6b !important;
42      padding: 12px 20px !important;
43    }
44    
45    .koi-widget-quick-action {
46      border-radius: 25px !important;
47      border: 2px solid #ff6b6b !important;
48      background: rgba(255, 107, 107, 0.1) !important;
49    }
50    
51    .koi-widget-quick-action:hover {
52      background: rgba(255, 107, 107, 0.2) !important;
53      transform: translateY(-2px) !important;
54    }
55  `
56};
57

Dark Mode Support

Automatic Dark Mode Detection

1window.KoiWidgetConfig = {
2  customCSS: `
3    @media (prefers-color-scheme: dark) {
4      .koi-widget-chat {
5        background: #1a1a1a !important;
6        color: #ffffff !important;
7      }
8      
9      .koi-widget-header {
10        background: #2d2d2d !important;
11      }
12      
13      .koi-widget-message.bot {
14        background: #2d2d2d !important;
15        color: #ffffff !important;
16      }
17      
18      .koi-widget-input {
19        background: #2d2d2d !important;
20        color: #ffffff !important;
21        border-color: #404040 !important;
22      }
23      
24      .koi-widget-quick-action {
25        background: #2d2d2d !important;
26        color: #ffffff !important;
27        border-color: #404040 !important;
28      }
29    }
30  `
31};
32

Manual Dark Mode Toggle

1// Toggle dark mode programmatically
2function toggleDarkMode(isDark) {
3  const darkModeCSS = `
4    .koi-widget-chat {
5      background: ${isDark ? '#1a1a1a' : '#ffffff'} !important;
6      color: ${isDark ? '#ffffff' : '#000000'} !important;
7    }
8    /* Add more dark mode styles */
9  `;
10  
11  KoiWidget.configure({
12    customCSS: darkModeCSS
13  });
14}
15

Responsive Design

Mobile Optimizations

1window.KoiWidgetConfig = {
2  customCSS: `
3    @media (max-width: 768px) {
4      .koi-widget-chat {
5        width: 100vw !important;
6        height: 100vh !important;
7        border-radius: 0 !important;
8        top: 0 !important;
9        left: 0 !important;
10        right: 0 !important;
11        bottom: 0 !important;
12      }
13      
14      .koi-widget-header {
15        border-radius: 0 !important;
16        padding: 20px 16px !important;
17      }
18      
19      .koi-widget-messages {
20        padding: 16px !important;
21      }
22      
23      .koi-widget-input-container {
24        padding: 16px !important;
25      }
26      
27      .koi-widget-button {
28        width: 60px !important;
29        height: 60px !important;
30        bottom: 20px !important;
31        right: 20px !important;
32      }
33    }
34    
35    @media (max-width: 480px) {
36      .koi-widget-message {
37        max-width: 85% !important;
38      }
39      
40      .koi-widget-quick-actions {
41        flex-direction: column !important;
42      }
43      
44      .koi-widget-quick-action {
45        width: 100% !important;
46        margin: 4px 0 !important;
47      }
48    }
49  `
50};
51

Animation Customization

Custom Animations

1window.KoiWidgetConfig = {
2  customCSS: `
3    .koi-widget-chat {
4      animation: slideInUp 0.3s ease-out !important;
5    }
6    
7    .koi-widget-message {
8      animation: fadeInUp 0.2s ease-out !important;
9    }
10    
11    .koi-widget-button {
12      animation: pulse 2s infinite !important;
13    }
14    
15    @keyframes slideInUp {
16      from {
17        transform: translateY(100%);
18        opacity: 0;
19      }
20      to {
21        transform: translateY(0);
22        opacity: 1;
23      }
24    }
25    
26    @keyframes fadeInUp {
27      from {
28        transform: translateY(20px);
29        opacity: 0;
30      }
31      to {
32        transform: translateY(0);
33        opacity: 1;
34      }
35    }
36    
37    @keyframes pulse {
38      0% {
39        box-shadow: 0 0 0 0 rgba(37, 99, 235, 0.7);
40      }
41      70% {
42        box-shadow: 0 0 0 10px rgba(37, 99, 235, 0);
43      }
44      100% {
45        box-shadow: 0 0 0 0 rgba(37, 99, 235, 0);
46      }
47    }
48  `
49};
50

Brand Integration

Custom Fonts

1window.KoiWidgetConfig = {
2  customCSS: `
3    @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap');
4    
5    .koi-widget-container * {
6      font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif !important;
7    }
8    
9    .koi-widget-header {
10      font-weight: 600 !important;
11    }
12    
13    .koi-widget-message {
14      font-weight: 400 !important;
15      line-height: 1.5 !important;
16    }
17  `
18};
19

Custom Logo in Header

1window.KoiWidgetConfig = {
2  customCSS: `
3    .koi-widget-header::before {
4      content: '';
5      background-image: url('https://your-domain.com/logo.png');
6      background-size: contain;
7      background-repeat: no-repeat;
8      width: 24px;
9      height: 24px;
10      margin-right: 8px;
11      display: inline-block;
12    }
13  `
14};
15

Advanced Techniques

CSS Variables for Dynamic Theming

1window.KoiWidgetConfig = {
2  customCSS: `
3    .koi-widget-container {
4      --primary-color: #2563eb;
5      --accent-color: #7c3aed;
6      --background-color: #ffffff;
7      --text-color: #1f2937;
8      --border-radius: 12px;
9      --shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
10    }
11    
12    .koi-widget-button {
13      background: var(--primary-color) !important;
14      border-radius: var(--border-radius) !important;
15      box-shadow: var(--shadow) !important;
16    }
17    
18    .koi-widget-chat {
19      background: var(--background-color) !important;
20      color: var(--text-color) !important;
21      border-radius: var(--border-radius) !important;
22    }
23  `
24};
25
26// Update theme dynamically
27function updateTheme(colors) {
28  const root = document.querySelector('.koi-widget-container');
29  Object.entries(colors).forEach(([key, value]) => {
30    root.style.setProperty(`--${key}`, value);
31  });
32}
33

Conditional Styling

1window.KoiWidgetConfig = {
2  customCSS: `
3    /* Style based on widget state */
4    .koi-widget-container[data-state="open"] .koi-widget-button {
5      transform: rotate(45deg) !important;
6    }
7    
8    /* Style based on position */
9    .koi-widget-container[data-position="top-left"] .koi-widget-chat {
10      border-radius: 0 12px 12px 12px !important;
11    }
12    
13    /* Style based on user type */
14    .koi-widget-container[data-user-type="premium"] .koi-widget-header {
15      background: linear-gradient(45deg, #ffd700, #ffed4e) !important;
16    }
17  `
18};
19

Troubleshooting Styles

CSS Specificity Issues

If your styles aren't applying:

  1. Use !important (recommended for widget styling)
  2. Increase specificity:
    1.koi-widget-container .koi-widget-button {
    2  /* More specific selector */
    3}
    4
  3. Check timing - apply styles after widget loads

Browser Compatibility

1window.KoiWidgetConfig = {
2  customCSS: `
3    /* Fallbacks for older browsers */
4    .koi-widget-button {
5      background: #2563eb; /* Fallback */
6      background: linear-gradient(135deg, #2563eb, #7c3aed); /* Modern */
7    }
8    
9    /* Vendor prefixes */
10    .koi-widget-chat {
11      -webkit-transform: translateZ(0);
12      transform: translateZ(0);
13    }
14  `
15};
16

For more styling examples and advanced techniques, check our examples section or contact support for custom styling assistance.