@futurebase/chat
v0.1.5
Published
Embeddable chat widget for FutureBase — React and Next.js integrations
Readme
@futurebase/chat
Embeddable chat widget for FutureBase. Drop-in React and Next.js components that add AI-powered customer support chat to your website.
Installation
npm install @futurebase/chatPeer Dependencies
React 18+ is required. Next.js 14+ is required for the Next.js integration.
# React only
npm install react react-dom
# Next.js
npm install react react-dom nextQuick Start
React
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:
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.
<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.
<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.
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:
import type {
ChatBubblePosition,
ChatBubbleProps,
ChatConfig,
ChatContextValue,
ChatStatusResponse,
ChatTheme,
FloatingMessage,
} from "@futurebase/chat";ChatTheme
type ChatTheme = "light" | "dark";ChatBubblePosition
type ChatBubblePosition = "bottom-right" | "bottom-left";ChatConfig
type ChatConfig = {
wid: string;
embedUrl?: string;
serverUrl?: string;
externalUserId?: string;
ignorePaths?: string[];
};ChatStatusResponse
type ChatStatusResponse = {
status: "ok" | "ai-credits-exceeded" | "not-ok";
enabled: boolean;
brandingRemoved?: boolean;
chatBubbleColor?: string;
chatBubbleIcon?: string;
chatBubblePosition?: "left" | "right";
floatingMessages?: FloatingMessage[];
};FloatingMessage
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"toChatBubbleto switch the embed to dark mode - Responsive — adapts to mobile screens automatically
- Keyboard accessible — escape to close, proper ARIA labels
License
MIT