Embed React

A beautiful, customizable AI assistant widget for React and Next.js applications. Features a floating button with voice call and chat functionality, smooth animations, and flexible positioning.

Features

• 🎯 Floating Button: Clean, circular floating button with customizable positioning
• 📌 Dual Positioning Modes: Fixed (always visible) or Embedded (inline in components)
• 💬 Chat Interface: Real-time chat with message bubbles and input field
• 📞 Voice Call Interface: Voice call modal with mute/unmute and end call controls
• 🎨 Smooth Animations: Beautiful animations powered by Framer Motion
• 📱 Responsive Design: Works perfectly on desktop and mobile devices
• ⚙️ Highly Customizable: Flexible positioning and styling options
• 🔧 TypeScript Support: Full TypeScript support with comprehensive type definitions
• ⚡ Framework Agnostic: Works with both React and Next.js

Installation

npm install @revrag-ai/embed-react
# or
yarn add @revrag-ai/embed-react
# or
pnpm add @revrag-ai/embed-react

Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install react react-dom framer-motion clsx

Quick Start

1. Import Required Styles ⚠️ CRITICAL

🚨 IMPORTANT: You MUST import the CSS file for proper styling, otherwise you'll see unstyled elements:

import '@revrag-ai/embed-react/dist/ai-assistant-widget.css';

Troubleshooting: If you see lines or unstyled elements, you likely forgot this step. See CSS_IMPORT_GUIDE.md for detailed instructions.

2. Initialize the SDK

First, initialize the SDK with your API key:

import React from 'react';
import { useInitialize } from '@revrag-ai/embed-react';
import '@revrag-ai/embed-react/dist/ai-assistant-widget.css'; // Required!

function App() {
  const { isInitialized, error } = useInitialize('your-api-key-here');

  if (error) {
    return <div>Error: {error}</div>;
  }

  if (!isInitialized) {
    return <div>Initializing SDK...</div>;
  }

  return (
    <div>
      <h1>SDK Initialized Successfully!</h1>
      {/* Your app content */}
    </div>
  );
}

export default App;

2. Add the AI Widget

After initialization, add the AI Widget to your app:

import React from 'react';
import { EmbedButton } from '@revrag-ai/embed-react';
import '@revrag-ai/embed-react/dist/ai-assistant-widget.css'; // Required!

function App() {
  return (
    <div>
      {/* Your app content */}
      <h1>My Application</h1>
      
      {/* AI Widget with default positioning (bottom-right) */}
      <EmbedButton />
    </div>
  );
}

export default App;

3. Import CSS (Required)

Important: You must import the CSS file for the widget to display correctly:

import '@revrag-ai/embed-react/dist/ai-assistant-widget.css';

Usage Examples

Basic Usage

import React from 'react';
import { useInitialize, EmbedButton } from '@revrag-ai/embed-react';
import '@revrag-ai/embed-react/dist/ai-assistant-widget.css';

function App() {
  const { isInitialized, error } = useInitialize('your-api-key-here');

  if (error) return <div>Error: {error}</div>;
  if (!isInitialized) return <div>Initializing...</div>;

  return (
    <div>
      <h1>My App</h1>
      <EmbedButton />
    </div>
  );
}

Positioning Modes

The widget supports two positioning modes:

Fixed Positioning (Default)

Always visible on screen, stays in place while scrolling (like Intercom, Drift):

// Default - bottom-right
<EmbedButton />

// Custom position
<EmbedButton 
  positioning="fixed"
  position={{ bottom: '24px', left: '24px' }} 
/>

Embedded Positioning (New!)

Placed inline within your components, scrolls with content:

// Single embedded widget
<div className="support-section">
  <h2>Need Help?</h2>
  <EmbedButton positioning="embedded" />
</div>

// Multiple embedded widgets for different departments
<div className="support-grid">
  <div>
    <h3>Sales Support</h3>
    <EmbedButton positioning="embedded" />
  </div>
  <div>
    <h3>Technical Support</h3>
    <EmbedButton positioning="embedded" />
  </div>
</div>

📖 For detailed positioning guide and examples, see POSITIONING_GUIDE.md

Next.js Usage

// pages/_app.tsx or app/layout.tsx
import { EmbedButton } from '@revrag-ai/embed-react';
import '@revrag-ai/embed-react/dist/ai-assistant-widget.css';

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <EmbedButton />
    </>
  );
}

Multiple Widgets

function App() {
  return (
    <div>
      {/* Support widget in bottom-right */}
      <EmbedButton />
      
      {/* Sales widget in bottom-left */}
      <EmbedButton 
        position={{ bottom: '24px', left: '24px' }}
        className="sales-widget"
      />
    </div>
  );
}

Conditional Rendering

function App() {
  const [showWidget, setShowWidget] = useState(true);
  
  return (
    <div>
      {showWidget && <EmbedButton />}
      
      <button onClick={() => setShowWidget(!showWidget)}>
        Toggle Widget
      </button>
    </div>
  );
}

API Reference

useInitialize Hook

Manages SDK initialization and provides access to authenticated API requests.

const { isInitialized, isLoading, error } = useInitialize(apiKey, options);

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | apiKey | string | ✅ | Your API key for authentication | | options | SDKConfig | ❌ | Additional configuration options |

Return Values

| Property | Type | Description | |----------|------|-------------| | isInitialized | boolean | Whether the SDK is currently initialized | | isLoading | boolean | Whether an initialization is in progress | | error | string \| null | Any error message from initialization |

EmbedButton Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | PositionConfig | { bottom: '24px', right: '24px' } | Positioning configuration | | className | string | undefined | Additional CSS classes |

PositionConfig

interface PositionConfig {
  bottom?: string;
  right?: string;
  left?: string;
  top?: string;
}

Styling

Custom Styling

Override default styles using your own CSS:

/* Custom floating button styling */
.ai-widget-floating-btn {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
  border: none !important;
}

/* Custom modal styling */
.ai-widget-modal {
  border-radius: 16px !important;
  box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25) !important;
}

CSS Variables

The widget supports CSS custom properties for easy theming:

:root {
  --ai-widget-primary-color: #3b82f6;
  --ai-widget-background-color: #111827;
  --ai-widget-text-color: #ffffff;
}

Troubleshooting

Widget Not Showing

Make sure you've imported the CSS file:

import '@revrag-ai/embed-react/dist/ai-assistant-widget.css';

TypeScript Issues

Install required types:

npm install --save-dev @types/react @types/react-dom

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT License

Development

git clone https://github.com/revrag-ai/embed-react.git
cd embed-react
npm install
npm run dev