@embedapi/react/README.md

🚀 Build stunning AI chat interfaces in minutes! Production-ready React components with real-time streaming, Material-UI design, and zero configuration required. Transform your app with powerful, customizable AI chat features.

# @embedapi/react

🚀 Build Production-Ready AI Chat Interfaces in Minutes! 

Transform your React app with stunning AI chat interfaces powered by EmbedAPI. Get a fully customizable Material-UI chat component that works out of the box, or build your own with our powerful hooks.

## Why Choose @embedapi/react?

✨ **Zero Configuration Required**
- Drop in our `<AgentChat />` component and you're ready to go
- Beautiful Material-UI design works instantly

🎨 **Fully Customizable**
- Light/Dark themes included
- Style every component to match your brand
- Build custom interfaces with our hooks

⚡ **Built for Performance**
- Real-time streaming responses
- Optimized for production
- Built on modern React 18

🛠️ **Developer Friendly**
- TypeScript definitions included
- Extensive documentation
- Active community support

## Prerequisites

1. Create a free account at [EmbedAPI](https://embedapi.com)
2. Create an AI agent in your dashboard
3. Copy your agent ID (starts with `agent_...`)

## Quick Start

```bash
npm install @embedapi/react
```

### Basic Usage

```jsx
import React from 'react';
import { AgentChat } from '@embedapi/react';

function App() {
  return (
    <AgentChat
      agentId="your-agent-id"
      theme="light"
      placeholder="Type a message..."
      customStyles={{
        container: {
          maxWidth: '800px',
          margin: '0 auto'
        }
      }}
    />
  );
}

export default App;
```

That's it! You now have a professional AI chat interface in your app. 🎉

[View Demo](https://embedapi.com/demo) | [Read Docs](https://embedapi.com/docs) | [Join Discord](https://discord.gg/embedapi)

## Features

- 🤖 Pre-built `AgentChat` component with Material-UI interface
- 🎣 `useChat` hook for custom chat implementations  
- 🔄 Real-time streaming support
- ⚡ Easy integration with EmbedAPI services
- 🎨 Fully customizable components

## Installation

```bash
npm install @embedapi/react
```

That's it! All required dependencies are included.

## Components

### AgentChat

A fully-featured chat interface built with Material-UI, ready for production use.

```jsx
<AgentChat
  // Required
  agentId="agent_..."              // Your EmbedAPI agent ID

  // Optional
  theme="light"                    // 'light' or 'dark'
  initialMessages={[               // Initial messages to display
    {
      role: 'assistant',
      content: 'How can I help?'
    }
  ]}
  placeholder="Type a message..."  // Input placeholder text
  className=""                     // Additional CSS class
  containerWidth="100%"           // Width of the chat container
  maxHeight="600px"               // Maximum height of message area
  onError={(error) => {}}         // Error handling callback
  style={{}}                      // Additional inline styles
  customStyles={{                 // Custom styling for components
    container: {},               // Container styles
    messageContainer: {},        // Message area styles
    userMessage: {},            // User message bubble styles
    assistantMessage: {},       // Assistant message bubble styles
    inputContainer: {}          // Input area styles
  }}
/>
```

### Styling Guide

The component supports comprehensive styling through the `customStyles` prop:

```jsx
<AgentChat
  customStyles={{
    container: {
      // Styles for the outer container
      maxWidth: '800px',
      margin: '0 auto'
    },
    messageContainer: {
      // Styles for the messages area
      padding: '20px',
      backgroundColor: '#f5f5f5'
    },
    userMessage: {
      // Styles for user message bubbles
      backgroundColor: '#e3f2fd',
      borderRadius: '10px'
    },
    assistantMessage: {
      // Styles for assistant message bubbles
      backgroundColor: '#fff',
      borderRadius: '10px'
    },
    inputContainer: {
      // Styles for the input area
      borderTop: '1px solid #eee',
      padding: '20px'
    }
  }}
  onError={(error) => {}}         // Optional error handling
/>
```

## Hooks

### useChat

Build custom chat interfaces with our low-level hook:

```jsx
const {
  messages,        // Current chat messages
  isLoading,       // Loading state
  error,           // Error state
  currentMessage,  // Current message being processed
  sendMessage,     // Send a message without streaming
  streamMessage,   // Send a message with streaming
  reset,           // Reset the chat
  clearCache,      // Clear cached messages
  messageCount     // Number of messages currently stored
} = useChat({
  agentId: 'agent_...',
  enableCache: true,
  messageLimit: 10, // Limit the number of cached messages
  initialMessages: []
});
```

### Message Caching and Limits

The `useChat` hook includes built-in message caching with automatic limits:

- Messages are automatically cached in sessionStorage
- Conversations persist between page reloads
- Each agent has its own cache
- Cache can be disabled with `enableCache: false`
- Clear cache manually with `clearCache()`
- Limit the number of cached messages with `messageLimit` (default: 10)

### Advanced Example

Build a custom chat interface using the useChat hook with caching:

```jsx
import React, { useState } from 'react';
import { useChat } from '@embedapi/react';

function CustomChat() {
  const [input, setInput] = useState('');
  const {
    messages,
    isLoading,
    currentMessage,
    streamMessage,
    reset,
    clearCache,
    messageCount
  } = useChat({
    agentId: 'agent_...',
    enableCache: true,
    messageLimit: 20, // Custom message limit
    initialMessages: [
      { role: 'assistant', content: 'How can I help you today?' }
    ]
  });

  const handleSend = async (e) => {
    e.preventDefault();
    if (!input.trim() || isLoading) return;
    
    const message = input.trim();
    setInput('');
    await streamMessage(message);
  };

  const handleReset = () => {
    reset();        // Reset conversation
    clearCache();   // Clear cached messages
  };

  return (
    <div>
      <div>Messages: {messageCount}/20</div>
      {messages.map((msg, i) => (
        <div key={i} className={msg.role}>
          {msg.content}
        </div>
      ))}
      
      {isLoading && (
        <div className="loading">
          Typing: {currentMessage.content}
        </div>
      )}

      <form onSubmit={handleSend}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Type a message..."
          disabled={isLoading}
        />
        <button type="submit" disabled={isLoading || !input.trim()}>
          Send
        </button>
        <button type="button" onClick={handleReset}>
          Reset Chat
        </button>
      </form>
    </div>
  );
}

export default CustomChat;
```

## Customization

### Themes

The AgentChat component supports both light and dark themes:

```jsx
<AgentChat theme="dark" />
```

### Custom Styling

Customize any part of the chat interface:

```jsx
<AgentChat
  customStyles={{
    container: {
      boxShadow: '0 0 10px rgba(0,0,0,0.1)',
      borderRadius: '12px'
    },
    messageContainer: {
      padding: '20px'
    },
    userMessage: {
      background: '#e3f2fd'
    },
    assistantMessage: {
      background: '#f5f5f5'
    },
    inputContainer: {
      borderTop: '1px solid #eee'
    }
  }}
/>
```

## Coming Soon

- 📎 File attachments support
- 🔍 Message search functionality
- 💾 Message persistence
- 🔄 Context management
- 🎨 More UI components
- 🛠️ Additional utility hooks

## Contributing

We welcome contributions! Please see our Contributing Guide for details.

## License

MIT License - see LICENSE file for details.

## Support

- 📚 [Documentation](https://embedapi.com/docs)
- 🐛 [Issue Tracker](https://github.com/01tek)
- 💬 [Discord Community](https://discord.gg/01tek)