Try Omnifox free 7 days free. No credit card required.
Guides

Add Chat to an HTML, React or Next.js Site: Installing the Widget in a SPA

How to install website chat on static HTML, React, Next.js, Vue or Angular without duplicating the script, with client routing and user identification.

September 06, 2026
Add Chat to an HTML, React or Next.js Site: Installing the Widget in a SPA
In this article

    Adding chat to an HTML, React or Next.js site is a one-line job on a static page and a slightly more careful job in a single-page app. The script is the same in every case. What changes is where it lives so that it loads exactly once, keeps working when the router swaps views without a full reload, and knows who the logged-in user is without you exposing anything you should not.

    This is for the developer who got the ticket "add the chat widget" and wants it done properly in ten minutes instead of debugging two chat buttons on Friday: static HTML, React and Next.js, Vue and Nuxt, Angular, SPA pitfalls, CSP, and identifying authenticated users with a signed payload.

    The script you are installing

    Whatever the stack, the widget is a single async script that you copy from the dashboard (in Omnifox: Channels → your website chat channel → Install):

    <script src="https://omnifox.io/widget/loader.js" data-widget-key="YOUR_KEY" async></script>
    

    It is async, so it does not block rendering, and it mounts its own UI; no container element needed. The dashboard shows which domains the widget has loaded on and when it was last seen, a handy smoke test after a deploy.

    Static HTML: before the closing body tag

    For a plain HTML site, a static site generator (Eleventy, Hugo, Jekyll, Astro in static mode) or a templated server-rendered app (Rails, Laravel, Django), paste the line once in the shared layout, right before </body>. Every page that uses the layout gets the widget, and there is nothing else to do.

    If you have separate templates for checkout and marketing pages, install it everywhere and hide it on checkout with a URL trigger from the dashboard; that is easier to change later than a second template.

    React and Next.js: load it once in the layout

    The rule in any component framework is: the widget belongs to the app shell, not to a page component. A page component can mount and unmount many times; the app shell mounts once.

    Next.js App Router

    Use next/script with the afterInteractive strategy in the root layout:

    // app/layout.tsx
    import Script from "next/script";
    
    export default function RootLayout({ children }) {
      return (
        <html lang="en">
          <body>
            {children}
            <Script
              src="https://omnifox.io/widget/loader.js"
              data-widget-key="YOUR_KEY"
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    

    afterInteractive loads the script after hydration, which is right for a widget that has no business delaying first paint. beforeInteractive is for polyfills and consent managers, not chat.

    Next.js Pages Router

    Same idea in pages/_app.tsx (or _document for the raw tag): _app wraps every page and mounts once.

    Create React App, Vite, plain React

    Put the script tag in public/index.html before </body>, outside React's render cycle, so a re-render cannot re-mount it. If you must load it from a component (only after cookie consent, say), do it in a useEffect in the top-level App with an empty dependency array, guarded against React 18 Strict Mode:

    useEffect(() => {
      if (document.querySelector('script[src*="omnifox.io/widget/loader.js"]')) return;
      const s = document.createElement("script");
      s.src = "https://omnifox.io/widget/loader.js";
      s.dataset.widgetKey = "YOUR_KEY";
      s.async = true;
      document.body.appendChild(s);
    }, []);
    

    Strict Mode runs effects twice in development; without the guard you see two widgets locally and blame the library.

    Vue, Nuxt and Angular

    Framework Where to put the script Notes
    Vue (Vite) index.html before </body> Outside the Vue app; mounts once
    Nuxt 3 nuxt.config.ts → app.head.script array, or useHead in app.vue Set async: true; keep it in app.vue, not in a page
    Angular src/index.html before </body> Outside the Angular bootstrap; no service needed
    Any SSR framework The root layout or document template Never inside a route-level component

    SPA pitfalls: route changes, double mounts and CSP

    Three things go wrong in SPAs, all cheap to prevent.

    1. Route changes without a reload. In a SPA the URL changes but the document does not. URL triggers (contains, starts with, equals) need to see that navigation so the pricing bubble fires when the user clicks into /pricing from the nav, not only on a hard refresh. The widget listens for client-side navigation; you do not call anything on route change. Test it anyway via a link, not the address bar.
    2. Mounting twice. Causes: the script in both index.html and a component, Strict Mode effects without a guard, a layout that remounts on auth state change. Symptoms: two buttons, or one button that opens two panels. Fix: one location, one guard.
    3. Content Security Policy. With a strict CSP, allow the widget's origin in script-src, connect-src (API and real-time connection), frame-src and img-src (avatars, attachments). Add https://omnifox.io and its subdomains, then watch the console for the first blocked request and add the exact origin it reports rather than guessing. Under a CSP that blocks it, the widget simply does not appear.

    A smaller one: dark mode. The widget follows the visitor's system preference when set to auto in the dashboard, so there is no theme prop to pass. If your app has its own toggle rather than following the OS, pick a fixed mode that matches your default.

    Identify logged-in users with a signed payload

    In a SaaS dashboard or customer portal the visitor is not anonymous. You want the conversation attached to the right contact and no way to impersonate another user by editing a JavaScript variable. Your backend computes an HMAC of the user's ID with the channel secret from the dashboard, sends it to the frontend with the ID, and the frontend calls identify:

    // Rendered by your backend into the page, or fetched from an authenticated endpoint
    window.Omnifox.identify({
      user_id: "usr_48213",
      user_hash: "<HMAC computed server-side with the channel secret>"
    });
    

    Two rules. The secret never leaves your server; if it shows up in the browser's network tab, the setup is wrong. And call identify after the script has loaded and you know who the user is; on logout, the next anonymous visit simply starts without it.

    On the Omnifox side the contact is created or updated by that external identifier, so the same person chatting from the web app and later replying by email or WhatsApp lands in one record with the full history. That continuity is the reason to bother; what happens after the tab closes is covered in from website chat to WhatsApp or SMS.

    Verify the install before you close the ticket

    A short checklist that catches nearly every problem:

    • One script element in the DOM: document.querySelectorAll('script[src*="loader.js"]').length === 1.
    • Navigate client-side to a page with a URL trigger and confirm the trigger fires.
    • Open the console with CSP enabled and confirm no blocked requests from the widget's origin.
    • Log in as a test user and check the contact appears in the dashboard under the right identifier.
    • Confirm the four analytics events (widget_loaded, widget_opened, conversation_started, message_sent) reach dataLayer if you use GA4 or Tag Manager; they are pushed automatically when those globals exist (details in GA4 and your website chat).
    • Check the dashboard lists your domain under "installed on" with a recent timestamp.

    Frequently asked questions

    Why do I see two chat buttons in development?

    React 18 Strict Mode runs effects twice in development. If you inject the script from a useEffect, guard it with a querySelector check, or move the tag to index.html so React never touches it.

    Do URL triggers work when my app changes routes without reloading?

    Yes. The widget tracks client-side navigation in SPAs, so a trigger set to "URL starts with /pricing" fires when the user reaches that route through the app's router, not only on a full page load.

    Where does the HMAC for identify get computed?

    On your server, using the channel secret from the dashboard, and never in the browser. The frontend receives only the user ID and the resulting hash, then passes both to window.Omnifox.identify.

    One script, one place, one contact record

    The whole install is one line in the right file: index.html for Vite and Angular, the root layout with next/script in Next.js, app.vue or the config head in Nuxt. Add identify for authenticated users, allow the origin in CSP, and the widget becomes the front door to the same shared inbox your team uses for email, WhatsApp and SMS.

    Try it against a local build with a 7-day free trial: create a website chat channel, paste the key, and confirm your staging domain shows up as installed. The full feature list is on the website chat page.

    Ready to try it in your business?

    Bring WhatsApp, Instagram, Messenger, email and calls into one inbox, and let AI handle the first reply. Set it up today.

    7 days free. No credit card required.

    Comments (0)

    No comments yet. Be the first to share your thoughts.

    Leave a comment

    Your email is never published. Comments are moderated before appearing.

    Markdown supported. HTML is stripped.

    Read more

    Message us on WhatsApp