Install guides / Next.js
Install the SupportHQ widget in Next.js
Next.js apps should load third-party scripts with next/script rather than a raw script tag, so the framework can schedule the load after hydration. The SupportHQ dashboard generates a ready-made Next.js component; this guide walks through where it goes.
The component is a client component. In the App Router it belongs in the root layout so the widget is present on every route without remounting on navigation.
Requirements: Works with Next.js 13 and later, App Router or Pages Router.
Steps
- 1
Copy the Next.js snippet from SupportHQ
In the SupportHQ dashboard open your project, go to Integrations, choose Web chat, switch the framework selector to Next.js, and copy the component. It already has your project ID.
- 2
Create the component file
Save it as components/SupportHQWidget.tsx (or wherever you keep client components). Keep the "use client" directive at the top.
- 3
Render it once in the root layout
App Router: import it in app/layout.tsx and render it inside the body after {children}. Pages Router: render it in pages/_app.tsx.
- 4
Run and check
Start the dev server and open any route. The launcher should appear after the page becomes interactive. Client-side navigation keeps it mounted.
Where it goes: App Router: app/layout.tsx, inside body after children. Pages Router: pages/_app.tsx. One instance for the whole app.
The snippet
Replace YOUR_PROJECT_ID, or copy the ready-made version from Integrations, Web chat in your dashboard.
'use client'
import Script from 'next/script'
export default function SupportHQWidget() {
return (
<Script
src="https://cdn.supporthq.app/widget/latest/supporthq-widget.js"
strategy="afterInteractive"
onReady={() => {
window.SupportHQWidget?.init({
projectId: 'YOUR_PROJECT_ID',
})
}}
/>
)
}Things that go wrong on Next.js
- Rendering the component inside individual pages remounts it on every navigation. Put it in the layout.
- Do not use strategy="beforeInteractive": the init call needs the document body and would block hydration.
- If you use a Content Security Policy, allow script-src for cdn.supporthq.app and connect-src for api.supporthq.app.
- In React Strict Mode (development only) effects run twice. The Next.js snippet uses onReady, which is safe to re-run. If you write a custom effect, call SupportHQWidget.destroy() in the cleanup.
Verify it works
- Open a route in the browser. The launcher should appear once the page is interactive, and the Network tab should show supporthq-widget.js loading from the CDN after the main bundle.
- Navigate between routes using links. The launcher should persist without flashing or duplicating.
- Ask a question your knowledge base covers and confirm it replies from your content. Ask something it does not cover and confirm it hands off.
- Check the SupportHQ inbox for the test conversation.
FAQ
Can I open the widget from my own button?
Yes. After init, call window.SupportHQWidget?.open() from any click handler. There are also close(), show(), hide(), update(options), and destroy().
Where do I find my project ID?
In the SupportHQ dashboard, open your project, go to Integrations, and choose Web chat. The embed code shown there already contains your project ID and any options you set (theme color, position, required fields). Copy it from there instead of typing it.
Will the widget slow my site down?
The script loads from a CDN. Place it at the end of the body, or use the async pattern shown for React and Next.js, and it will not block your page from rendering. Your content paints first.
Can I put the widget inside the page instead of a floating bubble?
Yes. Add a container element and pass mode: "embedded" and, if needed, container: "#your-id" to init. The chat renders inside that element at the width and height you set.