npm package: @futurebase/chat
Description: Embeddable chat widget for FutureBase — React and Next.js integrations
Latest version: 0.1.6

# @futurebase/chat

Embeddable chat widget for [FutureBase](https://futurebase.io). Drop-in React and Next.js components that add AI-powered customer support chat to your website.

## Installation

```bash
npm install @futurebase/chat
```

### Peer Dependencies

React 18+ is required. Next.js 14+ is required for the Next.js integration.

```bash
# React only
npm install react react-dom

# Next.js
npm install react react-dom next
```

## Quick Start

### React

```tsx
import { ChatProvider, ChatBubble } from "@futurebase/chat/react";

function App() {
  return (
    <ChatProvider wid="your-website-id">
      <ChatBubble />
    </ChatProvider>
  );
}
```

### Next.js (App Router)

The Next.js entry point provides a `ChatBubble` that uses `usePathname()` for reliable route-change detection:

```tsx
import { ChatProvider } from "@futurebase/chat/nextjs";
import { ChatBubble } from "@futurebase/chat/nextjs";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <ChatProvider wid="your-website-id">
          {children}
          <ChatBubble />
        </ChatProvider>
      </body>
    </html>
  );
}
```

## Components

### `ChatProvider`

Required wrapper that provides the chat context to all child components. Handles the status check and open/close state.

```tsx
<ChatProvider
  wid="your-website-id"
  embedUrl="https://embed.futurebase.io"
  ignorePaths={["/admin/*", "/login"]}
>
  {children}
</ChatProvider>
```

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `wid` | `string` | Yes | Your website ID |
| `children` | `ReactNode` | Yes | Child components |
| `embedUrl` | `string` | No | Custom embed app URL |
| `serverUrl` | `string` | No | Custom API server URL |
| `externalUserId` | `string` | No | External user ID to associate with conversations |
| `ignorePaths` | `string[]` | No | Pathname patterns to hide the bubble on (supports trailing `*` wildcards) |

### `ChatBubble` (React)

Import from `@futurebase/chat/react`.

A floating chat button that opens an embedded chat iframe when clicked. Tracks the current page URL via the Navigation API and popstate events.

```tsx
<ChatBubble
  position="bottom-right"
  theme="dark"
  defaultTab="chat"
/>
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `ChatBubblePosition` | `"bottom-right"` | Screen position of the bubble |
| `theme` | `"light" \| "dark"` | `"light"` | Light or dark mode for the chat embed |
| `icon` | `ReactNode` | — | Custom icon for the bubble button |
| `defaultTab` | `"home" \| "chat" \| "help"` | — | Default tab when chat opens |
| `autoStartConversation` | `boolean` | — | Auto-start a conversation on mount |

### `ChatBubble` (Next.js)

Import from `@futurebase/chat/nextjs`.

Same as the React version, but uses `usePathname()` from `next/navigation` for reliable route tracking in the App Router. Accepts the same props as the React `ChatBubble` (without `currentPath`).

## Hooks

### `useChat()`

Access the chat context from any component inside `ChatProvider`.

```tsx
import { useChat } from "@futurebase/chat/react";
// or
import { useChat } from "@futurebase/chat/nextjs";

function CustomChatButton() {
  const { isOpen, open, close, toggle, isEnabled, isLoading } = useChat();

  if (isLoading || !isEnabled) return null;

  return <button onClick={toggle}>{isOpen ? "Close" : "Chat"}</button>;
}
```

**Returns `ChatContextValue`:**

| Property | Type | Description |
|----------|------|-------------|
| `wid` | `string` | Website ID |
| `isOpen` | `boolean` | Whether the chat is currently open |
| `open` | `() => void` | Open the chat |
| `close` | `() => void` | Close the chat |
| `toggle` | `() => void` | Toggle the chat |
| `isEnabled` | `boolean` | Whether the widget is enabled (status check passed) |
| `isLoading` | `boolean` | Whether the status check is still loading |
| `status` | `ChatStatusResponse \| null` | Full status response from the server |

## Types

All types are exported from the root entry point:

```tsx
import type {
  ChatBubblePosition,
  ChatBubbleProps,
  ChatConfig,
  ChatContextValue,
  ChatStatusResponse,
  ChatTheme,
  FloatingMessage,
} from "@futurebase/chat";
```

### `ChatTheme`

```ts
type ChatTheme = "light" | "dark";
```

### `ChatBubblePosition`

```ts
type ChatBubblePosition = "bottom-right" | "bottom-left";
```

### `ChatConfig`

```ts
type ChatConfig = {
  wid: string;
  embedUrl?: string;
  serverUrl?: string;
  externalUserId?: string;
  ignorePaths?: string[];
};
```

### `ChatStatusResponse`

```ts
type ChatStatusResponse = {
  status: "ok" | "ai-credits-exceeded" | "not-ok";
  enabled: boolean;
  brandingRemoved?: boolean;
  chatBubbleColor?: string;
  chatBubbleIcon?: string;
  chatBubblePosition?: "left" | "right";
  floatingMessages?: FloatingMessage[];
};
```

### `FloatingMessage`

```ts
type FloatingMessage = {
  id: string;
  content: string;
  order: number;
  dismissable: boolean;
  displayDurationMs: number;
  triggerDelayMs: number;
};
```

## Features

- **Floating messages** — configure timed popup messages that appear near the chat bubble to engage users
- **Ignore paths** — hide the chat widget on specific pages using pathname patterns with wildcard support
- **Dark mode** — pass `theme="dark"` to `ChatBubble` to switch the embed to dark mode
- **Responsive** — adapts to mobile screens automatically
- **Keyboard accessible** — escape to close, proper ARIA labels

## License

MIT