Component Props

Complete API reference for the <InAppAI /> component.

Required Props

These props must be provided:

agentId

Type: string
Required: Yes
Description: Your AI agent ID from the InAppAI platform

<InAppAI agentId="your-agent-id" />

Get your agent ID from app.inappai.com.

messages

Type: Message[]
Required: Yes
Description: Array of conversation messages

const [messages, setMessages] = useState<Message[]>([]);

<InAppAI
  messages={messages}
  onMessagesChange={setMessages}
/>

See Message type for details.

onMessagesChange

Type: (messages: Message[]) => void
Required: Yes
Description: Callback when messages array changes

<InAppAI
  messages={messages}
  onMessagesChange={(newMessages) => {
    setMessages(newMessages);
    // Optionally save to backend or localStorage
  }}
/>

Display Configuration

displayMode

Type: 'popup' | 'sidebar-left' | 'sidebar-right' | 'panel-left' | 'panel-right' | 'embedded'
Default: 'popup'
Description: Layout mode for the chat interface

{/* Popup with floating button */}
<InAppAI displayMode="popup" />

{/* Sidebar overlay */}
<InAppAI displayMode="sidebar-right" />

{/* Resizable panel */}
<InAppAI displayMode="panel-left" />

{/* Embedded in your layout */}
<InAppAI displayMode="embedded" />

See Display Modes Guide for details.

position

Type: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
Default: 'bottom-right'
Description: Button position (popup mode only)

<InAppAI
  displayMode="popup"
  position="bottom-left"
/>

defaultFolded

Type: boolean
Default: false
Description: Start in folded state (sidebar/panel mode only)

<InAppAI
  displayMode="sidebar-right"
  defaultFolded={true}
/>

showHeader

Type: boolean
Default: true
Description: Show/hide the chat header

<InAppAI
  displayMode="embedded"
  showHeader={false}  // Hide header for custom layouts
/>

Styling & Theming

theme

Type: 'light' | 'dark' | 'professional' | 'playful' | 'minimal' | 'ocean' | 'sunset'
Default: 'light'
Description: Built-in theme to use

<InAppAI theme="dark" />

See Themes Guide for preview and details.

customStyles

Type: CustomStyles
Default: {}
Description: Override theme with custom styles

<InAppAI
  theme="light"
  customStyles={{
    primaryColor: '#6366f1',
    buttonIcon: '💬',
    headerTitle: 'Support',
    windowWidth: '500px',
  }}
/>

See CustomStyles API for all available properties.

Context & Data

context

Type: Record<string, any> | (() => Record<string, any>)
Default: undefined
Description: Application context sent to AI with each message

Static context (object):

<InAppAI
  context={{
    page: 'dashboard',
    userId: user.id,
    userRole: user.role,
  }}
/>

Dynamic context (function):

<InAppAI
  context={() => ({
    currentUrl: window.location.pathname,
    scrollPosition: window.scrollY,
    selectedText: window.getSelection()?.toString(),
  })}
/>

See Context Guide for best practices.

conversationId

Type: string
Default: Auto-generated
Description: Conversation identifier sent to backend

<InAppAI
  conversationId="user-123-support"
  messages={messages}
  onMessagesChange={setMessages}
/>

Useful for:

Multi-conversation apps
Backend conversation tracking
Analytics and logging

Tools & Function Calling

tools

Type: Tool[]
Default: []
Description: Array of tools the AI can execute

const tools: Tool[] = [
  {
    name: 'search',
    description: 'Search for information',
    parameters: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query' },
      },
      required: ['query'],
    },
    handler: async ({ query }) => {
      const results = await search(query);
      return { success: true, results };
    },
  },
];

<InAppAI tools={tools} />

See Tools Guide for complete documentation.

Panel-Specific Props

These props only apply when displayMode is panel-left or panel-right:

panelMinWidth

Type: string
Default: '20%'
Description: Minimum panel width (percentage or pixels)

<InAppAI
  displayMode="panel-right"
  panelMinWidth="300px"
/>

panelMaxWidth

Type: string
Default: '33.33%'
Description: Maximum panel width (percentage or pixels)

<InAppAI
  displayMode="panel-right"
  panelMaxWidth="50%"
/>

panelDefaultWidth

Type: string
Default: '25%'
Description: Initial panel width

<InAppAI
  displayMode="panel-right"
  panelDefaultWidth="400px"
/>

onPanelResize

Type: (width: number) => void
Default: undefined
Description: Callback when panel is resized

<InAppAI
  displayMode="panel-right"
  onPanelResize={(width) => {
    console.log('Panel width:', width);
    localStorage.setItem('panelWidth', width.toString());
  }}
/>

Authentication

authToken

Type: string | (() => string | null | undefined)
Default: undefined
Description: JWT token for per-user rate limiting and identification

Static token (string):

<InAppAI
  agentId="your-agent-id"
  messages={messages}
  onMessagesChange={setMessages}
  authToken={user.token}
/>

Dynamic token (function):

<InAppAI
  agentId="your-agent-id"
  messages={messages}
  onMessagesChange={setMessages}
  authToken={() => localStorage.getItem('authToken')}
/>

The function form is useful when:

Tokens may be refreshed during the session
Token retrieval is async or conditional
You want to return null to indicate unauthenticated state

See Authentication Guide for complete documentation.

Endpoint Configuration

endpoint

Type: string
Default: 'https://api.inappai.com/api'
Description: Custom API endpoint (for self-hosted backends)

<InAppAI
  endpoint="https://your-backend.com/api"
  agentId="your-agent-id"
  messages={messages}
  onMessagesChange={setMessages}
/>

Note: Most users don’t need to set this - the default InAppAI backend is used automatically.

Complete Example

import { useState } from 'react';
import { InAppAI, Message, Tool } from '@inappai/react';
import '@inappai/react/styles.css';

function App() {
  const [messages, setMessages] = useState<Message[]>([]);

  const tools: Tool[] = [
    {
      name: 'getWeather',
      description: 'Get current weather for a city',
      parameters: {
        type: 'object',
        properties: {
          city: { type: 'string', description: 'City name' },
        },
        required: ['city'],
      },
      handler: async ({ city }) => {
        // Fetch weather data
        return { temperature: 72, condition: 'Sunny' };
      },
    },
  ];

  return (
    <InAppAI
      // Required
      agentId="your-agent-id"
      messages={messages}
      onMessagesChange={setMessages}

      // Display
      displayMode="sidebar-right"
      position="bottom-right"
      defaultFolded={false}
      showHeader={true}

      // Styling
      theme="professional"
      customStyles={{
        headerTitle: 'Customer Support',
        buttonIcon: '💬',
        primaryColor: '#6366f1',
      }}

      // Context & Data
      context={() => ({
        page: window.location.pathname,
        userId: 'user-123',
      })}
      conversationId="support-chat-1"

      // Tools
      tools={tools}

      // Panel (if using panel mode)
      panelMinWidth="300px"
      panelMaxWidth="600px"
      panelDefaultWidth="400px"
      onPanelResize={(width) => console.log('Width:', width)}
    />
  );
}

TypeScript Support

All props are fully typed. Import types from the package:

import type { InAppAIProps, Message, Tool, CustomStyles } from '@inappai/react';

See TypeScript Types for complete type definitions.

Next Steps

Types - Type definitions
Styling - Complete styling API
Display Modes - Choose the right layout

Documentation