Chat Widget — Next.js
Add the FutureBase AI chat widget to a Next.js application using the @futurebase/chat package.
Installation
npm install @futurebase/chatQuick start (App Router)
Add ChatProvider and ChatBubble to your root layout
Import from @futurebase/chat/nextjs and add both components to your root layout file:
import { ChatProvider, ChatBubble } from "@futurebase/chat/nextjs";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<ChatProvider wid="YOUR_WEBSITE_ID">
{children}
<ChatBubble />
</ChatProvider>
</body>
</html>
);
}Verify the widget loads
Run your app with next dev and you should see the chat bubble in the bottom-right corner of the page.
Replace YOUR_WEBSITE_ID with the website ID from your FutureBase dashboard under Settings.
Why use the Next.js entry point?
The @futurebase/chat/nextjs entry point re-exports ChatProvider and useChat from the React version, but provides a Next.js-specific ChatBubble that uses usePathname() from next/navigation for reliable route-change detection in the App Router.
This means:
- Page navigations are tracked accurately, even with client-side transitions.
- The
ignorePathsconfiguration works reliably across route changes. - The embed iframe always knows which page the user is on.
If you use the base React ChatBubble in a Next.js app, it falls back to the Navigation API and popstate events, which may miss some App Router transitions.
Props and hook
The Next.js version accepts the same props as the React version:
- ChatProvider props — see React ChatProvider props
- ChatBubble props — see React ChatBubble props
- useChat() hook — see React useChat()
import { useChat } from "@futurebase/chat/nextjs";Client components
All components exported from @futurebase/chat/nextjs are client components — the "use client" directive is already included in the package exports. You do not need to add it yourself or create a wrapper component.
Hiding the widget on specific pages
Use the ignorePaths prop on ChatProvider to hide the chat bubble on certain routes:
<ChatProvider
wid="YOUR_WEBSITE_ID"
ignorePaths={["/admin/*", "/login", "/signup"]}
>
{children}
<ChatBubble />
</ChatProvider>Patterns support trailing * wildcards. For example, "/admin/*" hides the bubble on /admin/settings, /admin/users, and any other path starting with /admin/.