> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onsleek.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Customization

> Brand and customize the AI chat experience to match your application

## Overview

The AI Chat SDK provides customization options to ensure the chat experience seamlessly matches your application's brand identity. You can customize branding, colors, fonts, and layout.

## Brand configuration

Configure your brand identity using the `brand` option available in `chatConfig`, `badgeConfig`, and `inlineConfig`.

```typescript theme={null}
chatConfig: {
  brand: {
    name: 'Your Brand',
    logoUrl: 'https://your-app.com/logo.png',
  },
}
```

### Brand options

| Option    | Type              | Description                               |
| --------- | ----------------- | ----------------------------------------- |
| `name`    | `string`          | Your brand name displayed in the UI       |
| `logoUrl` | `string`          | URL to your logo image                    |
| `logo`    | `React.ReactNode` | React component for custom logo rendering |

**Logo requirements**:

* **Format**: PNG, SVG, or JPG
* **Size**: 200x200px minimum (square aspect ratio recommended)
* **Background**: Transparent PNG recommended
* **File size**: `<100KB` for best performance

### Using a custom logo component

For React applications, you can pass a custom logo component:

```tsx theme={null}
import { MyLogo } from './components/MyLogo';

chatConfig: {
  brand: {
    name: 'Your Brand',
    logo: <MyLogo width={32} height={32} />,
  },
}
```

## Color customization

Configure colors using the `styling` option available in `chatConfig`, `badgeConfig`, and `inlineConfig`.

```typescript theme={null}
chatConfig: {
  styling: {
    primaryColor: '#5C59FE',
    primaryColorDarkMode: '#8B87FF',
    colorMode: 'system',
  },
}
```

### Styling options

| Option                 | Type                            | Default             | Description                        |
| ---------------------- | ------------------------------- | ------------------- | ---------------------------------- |
| `primaryColor`         | `string`                        | `#5C59FE`           | Primary brand color for light mode |
| `primaryColorDarkMode` | `string`                        | (uses primaryColor) | Primary brand color for dark mode  |
| `colorMode`            | `'light' \| 'dark' \| 'system'` | `'system'`          | Color mode preference              |

### Color mode

Control how the SDK handles light and dark themes:

* **`'system'`** (default): Automatically matches the user's system preference
* **`'light'`**: Always use light mode colors
* **`'dark'`**: Always use dark mode colors

```typescript theme={null}
chatConfig: {
  styling: {
    colorMode: 'system',  // Respects user's OS preference
  },
}
```

### Brand color examples

<Tabs>
  <Tab title="Blue theme">
    ```typescript theme={null}
    styling: {
      primaryColor: '#2563eb',
      primaryColorDarkMode: '#60a5fa',
      colorMode: 'system',
    }
    ```
  </Tab>

  <Tab title="Green theme">
    ```typescript theme={null}
    styling: {
      primaryColor: '#059669',
      primaryColorDarkMode: '#34d399',
      colorMode: 'system',
    }
    ```
  </Tab>

  <Tab title="Purple theme">
    ```typescript theme={null}
    styling: {
      primaryColor: '#7c3aed',
      primaryColorDarkMode: '#a78bfa',
      colorMode: 'system',
    }
    ```
  </Tab>

  <Tab title="Orange theme">
    ```typescript theme={null}
    styling: {
      primaryColor: '#ea580c',
      primaryColorDarkMode: '#fb923c',
      colorMode: 'system',
    }
    ```
  </Tab>
</Tabs>

<Note>
  Ensure your custom font is loaded on the page before initializing the SDK.
</Note>

## Assistant configuration

Configure the AI assistant's identity using the `assistant` option.

```typescript theme={null}
chatConfig: {
  assistant: {
    name: 'Shopping Assistant',
    description: 'Your AI shopping helper',
    settingsUrl: 'https://example.com/settings',
  },
}
```

### Assistant options

| Option        | Type     | Description                       |
| ------------- | -------- | --------------------------------- |
| `name`        | `string` | Name displayed in the chat header |
| `description` | `string` | Description shown below the name  |
| `settingsUrl` | `string` | Link to settings page (optional)  |

## Layout customization

### Position and size

Control where the chat panel appears on the page:

```typescript theme={null}
chatConfig: {
  layout: {
    position: {
      right: '0px',
      bottom: '0px',
    },
    size: {
      width: '400px',
      height: '100vh',
    },
  },
}
```

### Common layout patterns

<Tabs>
  <Tab title="Right sidebar (default)">
    ```typescript theme={null}
    layout: {
      position: {
        right: '0px',
        bottom: '0px',
      },
      size: {
        width: '400px',
        height: '100vh',
      },
    }
    ```
  </Tab>

  <Tab title="Floating window">
    ```typescript theme={null}
    layout: {
      position: {
        right: '20px',
        bottom: '20px',
      },
      size: {
        width: '380px',
        height: '600px',
      },
    }
    ```
  </Tab>

  <Tab title="Bottom panel">
    ```typescript theme={null}
    layout: {
      position: {
        left: '0px',
        bottom: '0px',
      },
      size: {
        width: '100vw',
        height: '400px',
      },
    }
    ```
  </Tab>

  <Tab title="Left sidebar">
    ```typescript theme={null}
    layout: {
      position: {
        left: '0px',
        top: '0px',
      },
      size: {
        width: '400px',
        height: '100vh',
      },
    }
    ```
  </Tab>
</Tabs>

### Visual styling

Customize the panel's visual appearance:

```typescript theme={null}
chatConfig: {
  layout: {
    position: { right: '20px', bottom: '20px' },
    size: { width: '400px', height: '600px' },
  },
}
```

### Layout options

| Option            | Type     | Default   | Description          |
| ----------------- | -------- | --------- | -------------------- |
| `position.top`    | `string` | `'unset'` | Distance from top    |
| `position.right`  | `string` | `'0px'`   | Distance from right  |
| `position.bottom` | `string` | `'0px'`   | Distance from bottom |
| `position.left`   | `string` | `'unset'` | Distance from left   |
| `size.width`      | `string` | `'auto'`  | Panel width          |
| `size.height`     | `string` | `'auto'`  | Panel height         |
| `size.minWidth`   | `string` | `'auto'`  | Minimum width        |
| `size.maxWidth`   | `string` | `'none'`  | Maximum width        |
| `size.minHeight`  | `string` | `'auto'`  | Minimum height       |
| `size.maxHeight`  | `string` | `'none'`  | Maximum height       |

## Content customization

Customize text content displayed throughout the chat interface.

### Header

Customize the chat header with your logo and brand name:

```typescript theme={null}
chatConfig: {
  content: {
    header: {
      logo: <YourLogoComponent />,  // React node for custom logo
      logoUrl: 'https://example.com/logo.png',  // Or URL for logo image
      name: 'Your Brand AI',  // Brand name displayed in header
    },
  },
}
```

| Option    | Type              | Description                                                                                                                                           |
| --------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `logo`    | `React.ReactNode` | React component for custom logo rendering (height 36px, preserves aspect ratio). Falls back to `brand.logo` if neither `logo` nor `logoUrl` provided. |
| `logoUrl` | `string`          | URL to your logo image (height 36px, preserves aspect ratio). Falls back to `brand.logoUrl` if neither `logo` nor `logoUrl` provided.                 |
| `name`    | `string`          | Brand/product name displayed in the header. Falls back to `brand.name` if not provided.                                                               |

<Note>
  You can use either `logo` (React component) or `logoUrl` (image URL). If neither is provided, the SDK will fall back to the corresponding `brand` config values.
</Note>

### Default prompts

Provide suggested prompts for users:

```typescript theme={null}
chatConfig: {
  content: {
    defaultPrompts: ['Show me deals', 'Compare prices', 'Find discounts'],
  },
}
```

### Input placeholder

Customize the input field placeholder:

```typescript theme={null}
chatConfig: {
  content: {
    input: {
      placeholder: 'Ask about products...',
    },
  },
}
```

### Intro screen

Customize the intro message shown when chat opens:

```typescript theme={null}
chatConfig: {
  content: {
    intro: {
      title: 'Welcome!',
      message: 'How can I help you find what you need?',
    },
  },
}
```

### Loading messages

Customize loading messages that cycle while waiting for responses:

```typescript theme={null}
chatConfig: {
  content: {
    loading: {
      messages: ['Thinking...', 'Finding the best options...', 'Almost there...'],
    },
  },
}
```

### Error messages

Customize error message text:

```typescript theme={null}
chatConfig: {
  content: {
    error: {
      message: 'Something went wrong. Please try again.',
    },
  },
}
```

### Disclaimer text

Customize the disclaimer text:

```typescript theme={null}
chatConfig: {
  content: {
    disclaimerText: 'AI responses may not always be accurate. Please verify information.',
  },
}
```

## Badge customization

Customize the floating badge entry point:

```typescript theme={null}
badgeConfig: {
  // Control badge behavior
  allowExpand: true,
  autoCollapse: true,
  restoreBadgeOnChatClose: false,  // Set to true to restore badge after chat close

  // Branding (same options as chatConfig)
  brand: {
    name: 'Your Brand',
    logoUrl: 'https://your-app.com/logo.png',
  },

  // Styling (same options as chatConfig)
  styling: {
    primaryColor: '#5C59FE',
    colorMode: 'system',
  },

  // Badge-specific content
  content: {
    badge: {
      text: 'Ask AI',
    },
    onboarding: {
      title: 'Need help?',
      description: 'Click here to chat with our AI assistant',
    },
  },

  // Position the badge
  layout: {
    position: {
      right: '20px',
      bottom: '20px',
    },
  },
}
```

## Inline input customization

Customize the inline input entry point:

```typescript theme={null}
inlineConfig: {
  // Branding (same options as chatConfig)
  brand: {
    name: 'Your Brand',
  },

  // Styling (same options as chatConfig)
  styling: {
    primaryColor: '#5C59FE',
  },

  // Inline-specific content
  content: {
    input: {
      placeholder: 'Ask me anything...',
    },
  },

  // Specify where to render
  layout: {
    containerSelector: '#chat-container',
    insertPosition: 'append',  // or 'prepend'
  },
}
```

## Complete customization example

Here's a fully customized configuration:

```typescript theme={null}
import { initializeAiChatSdk } from '@sleek/ai-chat-sdk';

initializeAiChatSdk('your-api-key', {
  enableDebug: process.env.NODE_ENV === 'development',

  // Chat panel customization
  chatConfig: {
    usePageContext: true,
    messageLimitPerThread: 50,

    // Assistant identity
    assistant: {
      name: 'Shopping Assistant',
      description: 'Find the best deals and products',
    },

    // Branding
    brand: {
      name: 'Your Brand',
      logoUrl: 'https://your-app.com/logo.png',
    },

    // Colors and fonts
    styling: {
      primaryColor: '#6366f1',
      primaryColorDarkMode: '#818cf8',
      colorMode: 'system',
    },

    // Content
    content: {
      header: {
        logoUrl: 'https://your-app.com/header-logo.png',
        name: 'Shopping Assistant',
      },
      defaultPrompts: ['Show me deals', 'Compare prices', 'Find discounts'],
      disclaimerText: 'AI responses may not always be accurate',
      input: {
        placeholder: 'Ask about products...',
      },
      intro: {
        title: 'Welcome!',
        message: 'How can I help you find what you need?',
      },
      loading: {
        messages: ['Thinking...', 'Finding options...'],
      },
    },

    // Layout
    layout: {
      position: {
        right: '0px',
        bottom: '0px',
      },
      size: {
        width: '420px',
        height: '100vh',
      },
    },
  },

  // Badge customization
  badgeConfig: {
    allowExpand: true,
    autoCollapse: true,
    restoreBadgeOnChatClose: false,
    brand: {
      logoUrl: 'https://your-app.com/logo.png',
    },
    styling: {
      primaryColor: '#6366f1',
    },
    content: {
      badge: {
        text: 'Ask AI',
      },
    },
    layout: {
      position: {
        right: '20px',
        bottom: '20px',
      },
    },
  },

  // Data providers
  dataProviders: {
    offerRedirectUrlProvider: async (url) => null,
    merchantCashbackProvider: async (urls) => ({}),
  },
});
```

## Best practices

<AccordionGroup>
  <Accordion title="Maintain brand consistency">
    Use the same colors, logos, and fonts as your main application UI to create a cohesive experience.
  </Accordion>

  <Accordion title="Test both light and dark modes">
    If using `colorMode: 'system'`, test your customization in both light and dark modes:

    ```typescript theme={null}
    styling: {
      primaryColor: '#5C59FE',           // Good contrast on light backgrounds
      primaryColorDarkMode: '#8B87FF',   // Good contrast on dark backgrounds
      colorMode: 'system',
    }
    ```
  </Accordion>

  <Accordion title="Optimize logos">
    * Use SVG for scalable logos
    * Optimize PNG files to `<100KB`
    * Serve logos from a CDN for fast loading
    * Use transparent backgrounds
  </Accordion>

  <Accordion title="Use accessible colors">
    Ensure sufficient contrast for readability:

    * Text on backgrounds: 4.5:1 contrast ratio minimum
    * Interactive elements: 3:1 contrast ratio minimum

    Use tools like [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify.
  </Accordion>

  <Accordion title="Test responsiveness">
    Test the chat panel on different screen sizes to ensure it doesn't obscure critical page content.
  </Accordion>

  <Accordion title="Consider mobile users">
    For mobile, consider adjusting the layout:

    ```typescript theme={null}
    const isMobile = window.innerWidth < 768;

    chatConfig: {
      layout: {
        size: {
          width: isMobile ? '100vw' : '400px',
          height: isMobile ? '100vh' : '600px',
        },
      },
    }
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Logo not appearing">
    **Causes**:

    * Invalid logo URL
    * CORS restrictions on logo image
    * Logo URL not accessible

    **Solutions**:

    * Verify logo URL is accessible in browser
    * Host logo on a CDN with CORS enabled
    * Check browser DevTools for network errors
  </Accordion>

  <Accordion title="Colors look different than expected">
    **Causes**:

    * Browser color profile differences
    * System color mode affecting display
    * Transparency effects

    **Solutions**:

    * Test on multiple browsers
    * Use specific hex color values
    * Check `colorMode` setting
  </Accordion>

  <Accordion title="Custom font not applying">
    **Causes**:

    * Font not loaded before SDK initialization
    * Incorrect font family syntax

    **Solutions**:

    * Ensure font is loaded (use `document.fonts.ready`)
    * Include fallback fonts in the font family string
    * Verify font name matches the loaded font
  </Accordion>

  <Accordion title="Panel overlapping page content">
    **Causes**:

    * Incorrect positioning
    * Size too large for viewport

    **Solutions**:

    * Adjust position and size values
    * Use responsive sizing based on viewport
    * Test on different screen sizes
  </Accordion>
</AccordionGroup>