Chat Widget — React | FutureBase Docs

Add the FutureBase AI chat widget to any React application using the @futurebase/chat package.

Installation

npm install @futurebase/chat

Quick start

Wrap your app with ChatProvider

Import ChatProvider from @futurebase/chat/react and wrap your application. Pass your website ID as the wid prop — you can find it in your FutureBase dashboard under Settings.

import { ChatProvider } from "@futurebase/chat/react";

function App() {
  return (
    <ChatProvider wid="YOUR_WEBSITE_ID">
      {/* your app */}
    </ChatProvider>
  );
}

Add the ChatBubble component

Place ChatBubble anywhere inside the provider. It renders a floating chat button in the corner of the screen.

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

function App() {
  return (
    <ChatProvider wid="YOUR_WEBSITE_ID">
      <Main />
      <ChatBubble />
    </ChatProvider>
  );
}

Replace YOUR_WEBSITE_ID with the website ID from your FutureBase dashboard.

ChatProvider props

ChatProvider accepts the following props:

Prop	Type	Required	Description
`wid`	`string`	Yes	Your FutureBase website ID.
`children`	`ReactNode`	Yes	Child components to render inside the provider.
`embedUrl`	`string`	No	Override the embed app base URL (defaults to `https://embed.futurebase.io`).
`serverUrl`	`string`	No	Override the server API base URL (defaults to `https://api.futurebase.io`).
`externalUserId`	`string`	No	Associate conversations with a user ID from your system.
`ignorePaths`	`string[]`	No	Pathname patterns where the chat bubble should be hidden. Supports trailing `` wildcards (e.g. `"/admin/"`).

ChatBubble props

Prop	Type	Default	Description
`position`	`"bottom-right" \| "bottom-left"`	`"bottom-right"`	Screen corner where the bubble appears.
`theme`	`"light" \| "dark"`	`"light"`	Light or dark mode for the chat embed.
`icon`	`ReactNode`	—	Custom icon to render inside the bubble button.
`defaultTab`	`"home" \| "chat" \| "help"`	—	Which tab to show when the chat opens.
`autoStartConversation`	`boolean`	—	Automatically start a new conversation on mount.

useChat() hook

Access the chat state programmatically from any component inside ChatProvider:

import { useChat } from "@futurebase/chat/react";

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

  return (
    <button onClick={toggle}>
      {isOpen ? "Close chat" : "Open chat"}
    </button>
  );
}

Return value

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

Types

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";
};

Chat Widget — React

On this page