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}
8Chat 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}
16Chat 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}
20Messages
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}
32Input 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}
20Quick 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}
12Custom 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};
35Minimalist 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};
53Rounded 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};
57Dark 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};
32Manual 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}
15Responsive 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};
51Animation 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};
50Brand 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};
19Custom 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};
15Advanced 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}
33Conditional 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};
19Troubleshooting Styles
CSS Specificity Issues
If your styles aren't applying:
- Use
!important(recommended for widget styling) - Increase specificity:
1.koi-widget-container .koi-widget-button { 2 /* More specific selector */ 3} 4 - 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};
16For more styling examples and advanced techniques, check our examples section or contact support for custom styling assistance.