> ## 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 extension

## Overview

The AI Chat Extension SDK provides extensive customization options to ensure the chat experience seamlessly matches your extension's brand identity. You can customize logos, colors, fonts, layout, and content for both the chat badge and chat panel.

## Branding configuration

Both the chat badge and chat panel support brand customization through the `brand` property:

```typescript theme={null}
brand?: {
  logoUrl?: string;  // URL to your logo image
  name?: string;     // Your brand name
}
```

### Chat panel branding

```typescript theme={null}
await initializeAiChatExtensionSdk('your-api-key', {
  featureControls: {
    enableChatPanel: true,
  },
  chatConfig: {
    brand: {
      logoUrl: 'https://your-extension.com/panel-logo.png',
      name: 'Your Brand',
    },
  },
});
```

### Chat badge branding

```typescript theme={null}
await initializeAiChatExtensionSdk('your-api-key', {
  featureControls: {
    enableChatBadge: true,
  },
  badgeConfig: {
    brand: {
      logoUrl: 'https://your-extension.com/badge-logo.png',
      name: 'Your Brand',
    },
  },
});
```

**Logo requirements**:

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

## Styling configuration

Both the chat badge and chat panel support color and font customization through the `styling` property:

```typescript theme={null}
styling?: {
  primaryColor?: string;           // Primary color for light mode
  primaryColorDarkMode?: string;   // Primary color for dark mode
  colorMode?: 'light' | 'dark' | 'system';  // Color mode preference
}
```

### Color customization

```typescript theme={null}
chatConfig: {
  styling: {
    primaryColor: '#5C59FE',           // Light mode primary
    primaryColorDarkMode: '#8B87FF',   // Dark mode primary
    colorMode: 'system',               // Respect system preference
  },
}
```

**Color mode options**:

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

### Brand-specific examples

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

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

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

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

### Font customization

```typescript theme={null}
chatConfig: {
  styling: {
    fontFamily: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif',
  },
}
```

## Layout configuration

Control the position and size of the chat panel and badge using the `layout` property:

```typescript theme={null}
layout?: {
  position?: {
    top?: string;      // e.g., '0px', '10px', 'unset'
    right?: string;    // e.g., '0px', '20px', 'unset'
    bottom?: string;   // e.g., '0px', '10px', 'unset'
    left?: string;     // e.g., '0px', '20px', 'unset'
  };
  size?: {
    minWidth?: string;
    width?: string;
    maxWidth?: string;
    minHeight?: string;
    height?: string;
    maxHeight?: string;
  };
}
```

<Note>
  Use `chatConfig.isFloating` (defaults to `true`) to control whether floating panel styles (border, border-radius, box shadow) are applied to the chat panel.
</Note>

### Chat panel layout

```typescript theme={null}
chatConfig: {
  isFloating: true, // Apply floating panel styles (default: true)
  layout: {
    position: {
      top: '0px',
      right: '0px',
      bottom: '0px',
    },
    size: {
      width: '400px',
      maxHeight: '100vh',
    },
  },
}
```

### Badge layout

```typescript theme={null}
badgeConfig: {
  layout: {
    position: {
      bottom: '20px',
      right: '20px',
    },
  },
}
```

## Content customization

### Chat header

Customize the logo and name displayed in the chat panel header:

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

**Header logo requirements**:

* **Format**: PNG, SVG, or JPG
* **Height**: Logo will be scaled to height of 36px while preserving aspect ratio
* **Width**: Flexible - works with both square and wide logos

<Note>
  If `content.header` values are not provided, they will fall back to the `brand` configuration:

  * `header.logoUrl` falls back to `brand.logoUrl`
  * `header.name` falls back to `brand.name`

  This allows you to set branding once in `brand` and have it automatically apply to the header, or override specific header values when needed.
</Note>

### Chat panel content

Customize text and messages displayed in the chat panel:

```typescript theme={null}
chatConfig: {
  content: {
    // Header customization
    header: {
      logoUrl: 'https://your-extension.com/header-logo.png',
      name: 'Your Brand',
    },

    // Default suggested prompts
    defaultPrompts: [
      'Find me the best deals',
      'Compare prices for me',
      'Show product reviews',
    ],

    // Disclaimer text
    disclaimerText: 'AI responses may not always be accurate. Verify before purchasing.',

    // Hide provider attribution
    excludeProviderAttribution: true,

    // Error message customization
    error: {
      message: 'Unable to connect. Please try again.',
    },

    // Input field customization
    input: {
      placeholder: 'Ask me anything about products...',
    },

    // Intro screen customization
    intro: {
      title: 'Welcome!',
      message: 'How can I help you shop smarter today?',
    },

    // Loading messages (shown while AI is thinking)
    loading: {
      messages: ['Thinking...', 'Searching for deals...', 'Almost there...'],
    },

    // Rate limit message
    rateLimit: {
      message: 'You\'ve reached the message limit. Please try again later.',
    },

    // Reload prompt (when context changes)
    reload: {
      action: 'Start fresh',
      message: 'Your search has changed. Would you like to start a new conversation?',
    },
  },
}
```

### Badge content

Customize text displayed on the chat badge:

```typescript theme={null}
badgeConfig: {
  content: {
    badge: {
      text: 'Ask AI',
    },
    onboarding: {
      title: 'Meet your shopping assistant',
      description: 'Get personalized recommendations, compare prices, and find the best deals.',
    },
  },
}
```

## Assistant configuration

Customize the AI assistant's identity:

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

The same configuration is available for `badgeConfig.assistant`.

## Badge behavior

Control how the chat badge behaves:

```typescript theme={null}
badgeConfig: {
  // Allow the badge to expand on hover (default: true)
  allowExpand: true,

  // Auto-collapse the badge after a delay (default: true)
  autoCollapse: true,
}
```

**Behavior options**:

* `allowExpand: true`: Badge expands to show suggested prompts on hover
* `allowExpand: false`: Badge stays collapsed, only showing the icon
* `autoCollapse: true`: Badge collapses after a few seconds
* `autoCollapse: false`: Badge stays expanded with prompts visible

## Complete customization example

Here's a fully customized configuration:

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

await initializeAiChatExtensionSdk('your-api-key', {
  // Features
  featureControls: {
    enableChatBadge: true,
    enableChatPanel: true,
  },

  // Chat panel configuration
  chatConfig: {
    messageLimitPerThread: 75,
    isFloating: true, // Apply floating panel styles (border, border-radius, box shadow)

    // Content
    content: {
      header: {
        logoUrl: 'https://cdn.yourbrand.com/header-logo.png',
        name: 'Your Brand',
      },
      defaultPrompts: ['Find deals', 'Compare prices', 'Read reviews'],
      disclaimerText: 'AI-generated responses - please verify before purchasing',
      input: { placeholder: 'Ask me anything...' },
      intro: {
        title: 'Welcome!',
        message: 'How can I help you shop smarter today?',
      },
    },

    // Assistant identity
    assistant: {
      name: 'Shopping Assistant',
      description: 'Your AI-powered shopping helper',
    },

    // Branding
    brand: {
      logoUrl: 'https://cdn.yourbrand.com/panel-logo.png',
      name: 'Your Brand',
    },

    // Styling
    styling: {
      primaryColor: '#5C59FE',
      primaryColorDarkMode: '#8B87FF',
      colorMode: 'system',
      fontFamily: 'Inter, sans-serif',
    },

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

  // Badge configuration
  badgeConfig: {
    allowExpand: true,
    autoCollapse: false,

    content: {
      badge: { text: 'Ask AI' },
      onboarding: {
        title: 'Meet your shopping assistant',
        description: 'Get personalized recommendations and find the best deals',
      },
    },

    brand: {
      logoUrl: 'https://cdn.yourbrand.com/badge-logo.png',
      name: 'Your Brand',
    },

    styling: {
      primaryColor: '#5C59FE',
    },

    layout: {
      position: { bottom: '24px', right: '24px' },
    },
  },

  // Debug mode (development only)
  enableDebug: process.env.NODE_ENV === 'development',
});
```

## Preview your customization

To see your customization in action:

<Steps>
  <Step title="Test on Google Search">
    Navigate to Google Search and search for "best headphones" or another shopping query
  </Step>

  <Step title="Verify badge appearance">
    Check that the chat badge appears with your custom logo and styling
  </Step>

  <Step title="Open chat panel">
    Click the badge or a suggested prompt to open the chat panel
  </Step>

  <Step title="Verify panel styling">
    Confirm your custom colors, layout, and branding appear correctly in the panel
  </Step>
</Steps>

## Best practices

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

  <Accordion title="2. Test on light and dark pages">
    Use `colorMode: 'system'` and provide both `primaryColor` and `primaryColorDarkMode` to ensure your UI looks good in both light and dark modes.
  </Accordion>

  <Accordion title="3. Keep logos optimized">
    * Use SVG for scalable logos
    * Optimize PNG files to \<100KB
    * Serve logos from a CDN for fast loading
  </Accordion>

  <Accordion title="4. 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="5. Test panel layout">
    Test your layout on different screen sizes to ensure the panel doesn't obscure critical page content.
  </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 a browser
    * Host logo on a CDN with CORS enabled
    * Use HTTPS for logo URLs
  </Accordion>

  <Accordion title="Colors not applying">
    **Causes**:

    * Invalid color format
    * Wrong colorMode setting

    **Solutions**:

    * Use valid CSS color values (hex, rgb, hsl)
    * Check colorMode matches your testing environment
    * Provide both light and dark mode colors
  </Accordion>

  <Accordion title="Layout issues">
    **Causes**:

    * Conflicting position values
    * Invalid CSS units

    **Solutions**:

    * Use valid CSS units (px, vh, vw, %)
    * Test with specific position values before using 'unset'
    * Check for conflicting left/right or top/bottom values
  </Accordion>
</AccordionGroup>