Install in a Next.js app

Load the Voicello voice widget once for a whole Next.js app with the Script component in your root layout.

In a Next.js app, load the widget script once with the Script component from next/script, in the file that wraps every page. Do the shared setup in Install the widget first: you need a published agent, your domain under Verified domains, and the install code from the Deploy tab.

The install code has two values. In the steps below, copy the src value and the data-key value out of it and into the Script component.

App Router

Add the Script component to your root layout, app/layout.tsx:

import Script from 'next/script';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="PASTE_THE_SRC_VALUE_HERE"
          data-key="YOUR_WIDGET_KEY"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Pages Router

Add the same component to pages/_app.tsx:

import type { AppProps } from 'next/app';
import Script from 'next/script';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="PASTE_THE_SRC_VALUE_HERE"
        data-key="YOUR_WIDGET_KEY"
        strategy="afterInteractive"
      />
    </>
  );
}

Things to know

• Keep data-key on the Script component. The script reads its key from its own tag while it first runs, and next/script passes the attribute through to that tag.
• Use afterInteractive. It is the default, and it loads the widget after the page is usable. Do not use the worker strategy: the widget needs the page itself, which a web worker cannot reach.
• The widget loads once per page load. It stays in place while the router moves between pages.
• Showing it on some routes only. Put the Script component in the layout for those routes in place of the root layout. A visitor who lands on one of them keeps the widget until the browser loads a new document.
• Local development works. Add localhost under Verified domains to see the widget on next dev.

Check that it shows

Run your app and open it in the browser. The launcher button appears in the corner. If it does not, work through If the widget does not show.

If your app sets a Content Security Policy in next.config or in middleware, allow the address in the src value as both a script source and a frame source.