Advanced Customization

This guide covers advanced customization techniques beyond basic theming. For an introduction to themes and quick customizations, see the Themes Guide.

Customization Levels

InAppAI React offers three levels of customization:

Level	Approach	Use Case
Basic	Use built-in themes	Quick setup, standard appearance
Intermediate	Theme + customStyles	Brand colors, icons, text
Advanced	Full customStyles override	Complete visual control

Basic: Using Built-in Themes

Start with one of 7 built-in themes:

<InAppAI
  agentId="your-agent-id"
  messages={messages}
  onMessagesChange={setMessages}
  theme="professional"  // light, dark, professional, playful, minimal, ocean, sunset
/>

See Themes Guide for theme previews.

Intermediate: Theme + Overrides

Use a theme as a base and override specific properties:

<InAppAI
  theme="light"
  customStyles={{
    // Override just what you need
    primaryColor: '#6366f1',
    buttonIcon: '💬',
    headerTitle: 'Support',
  }}
/>

Common Overrides

Brand Colors

customStyles={{
  primaryColor: '#ff6b6b',
  buttonBackgroundColor: '#ff6b6b',
  userMessageBackground: '#ff6b6b',
}}

Custom Header

customStyles={{
  headerTitle: 'Customer Support',
  headerSubtitle: 'We reply in minutes',
  headerBackground: 'linear-gradient(to right, #667eea, #764ba2)',
  headerTextColor: '#ffffff',
}}

Button Customization

customStyles={{
  buttonIcon: '🛍️',
  buttonSize: '64px',
  buttonBackgroundColor: '#10b981',
  buttonBorderRadius: '16px',  // Rounded square instead of circle
}}

Typography

customStyles={{
  fontFamily: '"Inter", -apple-system, BlinkMacSystemFont, sans-serif',
  fontSize: '15px',
}}

Window Size

customStyles={{
  windowWidth: '450px',
  windowHeight: '700px',
  windowBorderRadius: '20px',
}}

Advanced: Full Custom Styling

For complete control, provide a comprehensive customStyles object:

const customStyles: CustomStyles = {
  // Primary branding
  primaryColor: '#6366f1',
  primaryGradient: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',

  // Chat button
  buttonBackgroundColor: '#6366f1',
  buttonTextColor: '#ffffff',
  buttonSize: '60px',
  buttonBorderRadius: '50%',
  buttonIcon: '💬',

  // Chat window
  windowWidth: '420px',
  windowHeight: '650px',
  windowBorderRadius: '16px',

  // Header
  headerBackground: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
  headerTextColor: '#ffffff',
  headerTitle: 'Support Assistant',
  headerSubtitle: 'How can we help?',

  // Message bubbles
  userMessageBackground: '#6366f1',
  userMessageColor: '#ffffff',
  assistantMessageBackground: '#f3f4f6',
  assistantMessageColor: '#1f2937',

  // Input area
  inputBackground: '#ffffff',
  inputTextColor: '#1f2937',
  inputBorderColor: '#e5e7eb',
  inputPlaceholder: 'Type your message...',

  // Typography
  fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
  fontSize: '15px',

  // Sidebar (for sidebar mode)
  sidebarWidth: '380px',
  sidebarFoldedWidth: '60px',

  // General
  borderRadius: '12px',
  boxShadow: '0 20px 60px rgba(0, 0, 0, 0.3)',
};

<InAppAI
  agentId="your-agent-id"
  messages={messages}
  onMessagesChange={setMessages}
  customStyles={customStyles}
/>

Industry-Specific Examples

E-Commerce

<InAppAI
  theme="light"
  customStyles={{
    buttonIcon: '🛒',
    primaryColor: '#10b981',
    headerTitle: 'Shopping Assistant',
    headerSubtitle: 'Need help finding something?',
    headerBackground: 'linear-gradient(135deg, #10b981 0%, #059669 100%)',
    inputPlaceholder: 'Ask about products, orders, returns...',
  }}
/>

Developer Tools

<InAppAI
  theme="dark"
  customStyles={{
    buttonIcon: '⚡',
    fontFamily: '"Fira Code", "JetBrains Mono", monospace',
    headerTitle: 'AI Assistant',
    headerSubtitle: 'Ask anything about the docs',
    primaryColor: '#a78bfa',
    userMessageBackground: '#7c3aed',
  }}
/>

Corporate/Enterprise

<InAppAI
  theme="professional"
  customStyles={{
    buttonIcon: '💼',
    primaryColor: '#2563eb',
    headerTitle: 'Enterprise Support',
    headerSubtitle: 'Available 24/7',
    windowWidth: '480px',
    fontSize: '14px',
  }}
/>

Healthcare

<InAppAI
  theme="minimal"
  customStyles={{
    buttonIcon: '🏥',
    primaryColor: '#0ea5e9',
    headerTitle: 'Patient Assistant',
    headerSubtitle: 'How can I help you today?',
    borderRadius: '8px',
  }}
/>

Responsive Customization

Using CSS Values

customStyles={{
  // Responsive window size
  windowWidth: 'min(450px, 90vw)',
  windowHeight: 'min(700px, 80vh)',

  // Responsive font
  fontSize: 'clamp(14px, 2vw, 16px)',

  // Responsive button
  buttonSize: 'clamp(56px, 10vw, 72px)',
}}

Theme-Based Styling

function App() {
  const [isDark, setIsDark] = useState(false);

  const customStyles: CustomStyles = {
    primaryColor: '#6366f1',
    // Dynamic based on theme
    assistantMessageBackground: isDark ? '#374151' : '#f3f4f6',
    assistantMessageColor: isDark ? '#f9fafb' : '#1f2937',
    inputBackground: isDark ? '#1f2937' : '#ffffff',
  };

  return (
    <InAppAI
      theme={isDark ? 'dark' : 'light'}
      customStyles={customStyles}
      // ...
    />
  );
}

Media Query Integration

function App() {
  const [isMobile, setIsMobile] = useState(window.innerWidth < 768);

  useEffect(() => {
    const handleResize = () => setIsMobile(window.innerWidth < 768);
    window.addEventListener('resize', handleResize);
    return () => window.removeEventListener('resize', handleResize);
  }, []);

  return (
    <InAppAI
      customStyles={{
        windowWidth: isMobile ? '100vw' : '420px',
        windowHeight: isMobile ? '100vh' : '650px',
        windowBorderRadius: isMobile ? '0' : '16px',
        buttonSize: isMobile ? '50px' : '60px',
      }}
      // ...
    />
  );
}

Using CSS Variables

Define Variables

/* styles.css */
:root {
  --brand-primary: #6366f1;
  --brand-secondary: #8b5cf6;
  --brand-accent: #ec4899;
  --font-body: 'Inter', -apple-system, sans-serif;
  --shadow-lg: 0 20px 60px rgba(0, 0, 0, 0.2);
}

[data-theme='dark'] {
  --brand-primary: #818cf8;
  --brand-secondary: #a78bfa;
}

Use in CustomStyles

customStyles={{
  primaryColor: 'var(--brand-primary)',
  headerBackground: 'var(--brand-secondary)',
  fontFamily: 'var(--font-body)',
  boxShadow: 'var(--shadow-lg)',
}}

This approach allows your chat to automatically adapt when your app’s theme changes.

Design System Integration

Tailwind CSS

// Extract colors from Tailwind config
const colors = {
  primary: '#6366f1',  // indigo-500
  secondary: '#8b5cf6',  // violet-500
  gray: {
    50: '#f9fafb',
    100: '#f3f4f6',
    700: '#374151',
    900: '#111827',
  }
};

<InAppAI
  customStyles={{
    primaryColor: colors.primary,
    userMessageBackground: colors.primary,
    assistantMessageBackground: colors.gray[100],
    assistantMessageColor: colors.gray[900],
  }}
/>

Chakra UI / Theme UI

import { useTheme } from '@chakra-ui/react';

function ChatWidget() {
  const theme = useTheme();

  return (
    <InAppAI
      customStyles={{
        primaryColor: theme.colors.brand[500],
        fontFamily: theme.fonts.body,
        borderRadius: theme.radii.lg,
      }}
      // ...
    />
  );
}

Material UI

import { useTheme } from '@mui/material';

function ChatWidget() {
  const theme = useTheme();

  return (
    <InAppAI
      customStyles={{
        primaryColor: theme.palette.primary.main,
        fontFamily: theme.typography.fontFamily,
        borderRadius: `${theme.shape.borderRadius}px`,
      }}
      // ...
    />
  );
}

Accessibility Considerations

Color Contrast

Ensure sufficient contrast ratios (WCAG AA minimum):

customStyles={{
  // Good: White text on dark background
  userMessageBackground: '#1f2937',
  userMessageColor: '#ffffff',

  // Good: Dark text on light background
  assistantMessageBackground: '#f3f4f6',
  assistantMessageColor: '#111827',

  // Avoid: Low contrast combinations
  // assistantMessageBackground: '#e5e7eb',
  // assistantMessageColor: '#9ca3af',  // Too low contrast!
}}

Focus Indicators

The component includes built-in focus indicators. If you customize colors, ensure buttons and inputs remain visible when focused.

Font Sizing

Use relative units for better accessibility:

customStyles={{
  fontSize: '1rem',  // Better than '16px'
}}

Performance Tips

Memoize customStyles to prevent unnecessary re-renders:

const customStyles = useMemo(() => ({
  primaryColor: '#6366f1',
  // ...
}), []);

Avoid inline object creation in render:

// Bad: Creates new object on every render
<InAppAI customStyles={{ primaryColor: '#6366f1' }} />

// Good: Stable reference
const customStyles = { primaryColor: '#6366f1' };
<InAppAI customStyles={customStyles} />

Best Practices

Start with a theme - Use built-in themes as a foundation
Override minimally - Only customize what’s necessary for brand alignment
Maintain consistency - Use the same border radius, shadows across properties
Test thoroughly - Check all display modes and screen sizes
Ensure accessibility - Verify color contrast and focus states
Document your choices - Comment why specific values were chosen

Next Steps

Custom Styles API - Complete property reference
Themes Guide - Built-in themes overview
Display Modes - Layout options

Documentation