Install in a React app

Load the Voicello voice widget once for a whole React app, from index.html or from a small component.

In a React app, load the widget script once for the whole app. The simplest way is your app's HTML file. If you cannot edit that file, a small component does the same job. 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.

For Next.js, use the Next.js guide.

Option 1: your HTML file

Paste the install code into your app's HTML file, just before the closing </body> tag. In a Vite app that file is index.html at the project root. In Create React App it is public/index.html.

HTML

    <div id="root"></div>
    <!-- Paste the install code from the Deploy tab on this line -->
  </body>
</html>

This is all a single page app needs. The script runs once when the page loads, and the widget stays in place while your router changes views.

Option 2: a component

Use this when the HTML file is out of your hands, or when the widget should load only for some visitors.

The install code has two values. Copy the src value and the data-key value out of it and into this component:

TSX

import { useEffect } from 'react';

// Both values come from the install code on your Deploy tab.
const SCRIPT_SRC = 'PASTE_THE_SRC_VALUE_HERE';
const WIDGET_KEY = 'YOUR_WIDGET_KEY';

export function VoiceWidget() {
  useEffect(() => {
    // Add the script once, even if this component mounts again.
    if (document.querySelector('script[data-voice-widget]')) return;

    const script = document.createElement('script');
    script.src = SCRIPT_SRC;
    script.async = true;
    script.dataset.key = WIDGET_KEY;
    script.dataset.voiceWidget = '';
    document.body.appendChild(script);
  }, []);

  return null;
}

Render it once, near the root of your app:

TSX

export function App() {
  return (
    <>
      <VoiceWidget />
      {/* the rest of your app */}
    </>
  );
}

Things to know

The widget loads once per page load. It stays on the page until the browser loads a new document. Removing the component later does not remove the widget.
Local development works. Add localhost under Verified domains to see the widget on your dev server.
Strict Mode is fine. React runs effects twice in development. The check at the top of the effect keeps the script from being added twice, and a second copy would be ignored anyway.

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.