Home Insight AI

SDK Customization Guide

Overview

The Home Insight AI SDK supports two layout modes and custom brand colors, making it easy to integrate seamlessly into your application's design.

Layout Modes

1. Popup Mode (Default)

Small chat widget that appears as a floating button in the corner.

React
<HomeInsightChat
  apiKey="hi_live_..."
  propertyId="your-property-id"
  layout="popup"  // Default
  position="bottom-right"  // or "bottom-left"
/>

Features:

  • 380px × 550px window
  • Toggle button to open/close
  • Positions: bottom-right or bottom-left
  • Non-intrusive, familiar interface
  • Good for general website integration

2. Sidebar Mode (NEW!)

Full-height sidebar that's toggleable on the right side of the screen.

React
<HomeInsightChat
  apiKey="hi_live_..."
  propertyId="your-property-id"
  layout="sidebar"
/>

Features:

  • 400px width, full screen height
  • Click bubble to toggle open/close
  • Slides in from the right
  • Perfect for property listing pages
  • More space for chat history
  • Mobile responsive (full width on phones)

Recommended Use Cases:

  • Real estate property detail pages
  • Home inspection report viewers
  • Dedicated chat/support pages
  • Applications where chat is the primary feature

Custom Brand Colors

Match your brand by customizing the primary color used throughout the widget.

React
<HomeInsightChat
  apiKey="hi_live_..."
  propertyId="your-property-id"
  primaryColor="#10b981"  // Your brand color
  accentColor="#059669"   // Darker shade for hover states
/>

Where Colors Are Applied:

  • Header background gradient
  • Toggle button background
  • Send button
  • Links and interactive elements
  • Progress indicators
  • File upload buttons

Color Examples:

| Brand | Primary Color | Accent Color | |-------|---------------|-------------- | Green | #10b981 | #059669 | | Purple | #8b5cf6 | #7c3aed | | Orange | #f59e0b | #d97706 | | Red | #ef4444 | #dc2626 | | Teal | #14b8a6 | #0d9488 |

Tips:

  • Use hex color codes (e.g., #10b981)
  • Accent color should be slightly darker for better hover states
  • Test colors against white text for accessibility (WCAG AA: 4.5:1 contrast)

Complete Examples

E-commerce Real Estate Site

React
<HomeInsightChat
  apiKey="hi_live_..."
  propertyId={currentProperty.id}
  layout="sidebar"
  primaryColor="#059669"  // Green theme
  accentColor="#047857"
/>

Real Estate Agency Portal

React
<HomeInsightChat
  apiKey="hi_live_..."
  propertyId={property.id}
  layout="popup"
  position="bottom-right"
  primaryColor="#dc2626"  // Red theme
  accentColor="#b91c1c"
/>

Property Management Dashboard

React
<HomeInsightChat
  apiKey="hi_live_..."
  propertyId={selectedProperty}
  layout="sidebar"
  primaryColor="#7c3aed"  // Purple theme
  accentColor="#6d28d9"
  theme="dark"  // Dark mode
/>

Property Listing Page with Sidebar

React
import { HomeInsightChat } from 'home-insight-ai-sdk';
import 'home-insight-ai-sdk/style.css';

export function PropertyDetailPage() {
  return (
    <div style={{ paddingRight: '420px' }}>  {/* Leave space for sidebar */}
      {/* Your property listing content */}
      <h1>Beautiful newly renovated home</h1>
      <p>1938 Marin Avenue, Berkeley, CA 94707</p>

      {/* Image gallery */}
      <div className="gallery">
        {/* ... */}
      </div>

      {/* Property details */}
      <div className="details">
        <h2>Property Details</h2>
        <p>3 bed • 2 bath • 1,850 sqft</p>
      </div>

      {/* Sidebar chat - always visible */}
      <HomeInsightChat
        apiKey="hi_live_..."
        propertyId="a3e532e2-d03a-4deb-bb3c-7f3d2cbc7141"
        layout="sidebar"
        primaryColor="#10b981"  // Your brand green
        accentColor="#059669"
        theme="light"
      />
    </div>
  );
}

CSS for responsive layout:

CSS
.content-area {
  padding-right: 420px;  /* 400px sidebar + 20px gap */
}

@media (max-width: 768px) {
  .content-area {
    padding-right: 0;  /* Reset on mobile */
  }
}

API Reference

HomeInsightChatProps

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | string | Required | Your API key | | propertyId | string | Optional | Property ID for multi-document chat | | analysisId | string | Optional | Single document ID (backward compatible) | | layout | 'popup' \| 'sidebar' | 'popup' | Widget layout mode | | position | 'bottom-right' \| 'bottom-left' | 'bottom-right' | Position (popup mode only) | | theme | 'light' \| 'dark' | 'light' | Color theme | | primaryColor | string | '#5b7cff' | Primary brand color (hex) | | accentColor | string | '#4a63d9' | Accent color for hover states (hex) | | apiBaseUrl | string | Production URL | API endpoint | | allowUpload | boolean | true | Enable file upload fallback |

Migration Guide

Upgrading from v1.0 to v2.0

The new customization features are backward compatible. Existing implementations will continue to work without changes.

Before:

React
<HomeInsightChat apiKey="..." propertyId="..." />

After (same result):

React
<HomeInsightChat
  apiKey="..."
  propertyId="..."
  layout="popup"  // Default
  primaryColor="#5b7cff"  // Default
/>

Adding Sidebar Mode

  1. Adjust page layout to accommodate 400px sidebar:

    CSS
    .content-area {
  padding-right: 420px;  /* 400px sidebar + 20px gap */
}

  2. Use sidebar layout:

    React
    <HomeInsightChat layout="sidebar" ... />

  3. Handle mobile responsiveness:

    • Sidebar automatically goes full-width on mobile (screens less than 768px)
    • Consider hiding sidebar on mobile and using popup instead

Best Practices

Color Selection

  1. Maintain Accessibility

    • Ensure 4.5:1 contrast ratio minimum against white text
    • Test with WebAIM Color Contrast Checker

  2. Consistency

    • Use the same colors as your main site header/CTA buttons
    • Accent color should be 10-15% darker than primary

  3. Testing

    • Test colors in both light and dark themes
    • Check hover states for visibility

Layout Selection

Use Popup Mode When:

  • Chat is secondary to main content
  • Multiple pages share the same widget
  • Screen space is limited
  • Mobile-first design

Use Sidebar Mode When:

  • Chat is the primary interaction
  • Property listing/detail pages
  • Dashboard or admin interfaces
  • Desktop-first design

Performance

  • Widget loads asynchronously (doesn't block page load)
  • Sidebar mode: ~37KB gzipped
  • Color customization: No bundle size impact (CSS variables)

Troubleshooting

Sidebar overlaps content

Solution: Add right padding to your content area:

CSS
.content {
  padding-right: 420px;
}

@media (max-width: 768px) {
  .content {
    padding-right: 0;  /* Reset on mobile */
  }
}

Colors not applying

Solution: Ensure you're passing valid hex color codes:

React
// ✅ Correct
primaryColor="#10b981"

// ❌ Incorrect
primaryColor="green"  // Use hex instead
primaryColor="rgb(16, 185, 129)"  // Use hex instead

Sidebar not showing

Solution: Check that layout="sidebar" is set:

React
<HomeInsightChat layout="sidebar" ... />

Support

For questions or issues:

  • Documentation: https://docs.homeinsightai.com
  • GitHub: https://github.com/homeinsightai/sdk
  • Email: support@homeinsightai.com
Home Insight AI - Developer Portal