React Component
Install the widget as a React component with props, callbacks, and refs
To add the widget to a React app, install @wexio/messenger-widget-react. The package is a thin wrapper (about 13 KB) that renders the <wexio-widget> web component and loads it from https://cdn.wexio.io/widget/widget.js. The widget runs in a Shadow DOM, so its styles never leak into your app and yours never leak into the widget.
Because the widget loads from the CDN, new widget features reach your site without an npm upgrade. Upgrade the package only when you need a new prop or type. Versions before 1.8.0 bundle the whole widget (about 3.2 MB), so one upgrade to 1.8.0 makes your site evergreen. A widget release reaches your site within about a minute, because widget.js is cached for 60 seconds and then revalidated.
If your site sends a Content-Security-Policy, allow https://cdn.wexio.io in script-src. If the script is blocked, the widget does not appear and the console shows a warning.
Install
npm install @wexio/messenger-widget-react
# or
yarn add @wexio/messenger-widget-reactPeer dependencies are react >= 18 and react-dom >= 18.
Basic Usage
Render the component once, near the root of your app:
import { WexioWidget } from "@wexio/messenger-widget-react";
export default function App() {
return (
<>
<YourAppShell />
<WexioWidget publicKey="pk_live_..." />
</>
);
}Props
| Prop | Type | Purpose |
|---|---|---|
publicKey | string | Your widget's public key. Omit for demo mode. |
user | VisitorIdentity | A known-visitor proof - jwt, googleIdToken, or userId + userHash. Memoise it. See Authentication. |
config | InjectableWidgetConfig | A pre-resolved config; skips the bootstrap fetch. The widget still uses publicKey for the visitor handshake. |
theme | "light" | "dark" | "auto" | Force the widget theme from your page. Update it when your site switches theme and the widget follows. It wins over the dashboard default and the visitor's system setting. Omit it to let the widget decide. |
configOverride | Partial<WidgetConfig> | Presentation fields merged over the saved config, such as theme, greeting or features. Memoise it. See config reference. |
defaultOpen | boolean | Opens the panel on mount. After that the visitor can close it. |
open | boolean | Controlled open state. Keep it in sync from onOpen and onClose. Omit it for an uncontrolled widget. |
previewTab | { tab, nonce, article? } | Go to a tab or article and open the panel. A new nonce repeats the request. |
offset | { x?: number; y?: number } | Move the launcher away from its corner, in px. |
runtimeUrl | string | Where the widget loads from. The default is https://cdn.wexio.io/widget/widget.js, always the latest release. Set it to pin a release, such as https://cdn.wexio.io/widget/v1.8.0/widget.js (1.8.0 or later), or to a self-hosted copy. Read once per page. |
onResize | (size: { width: number; height: number }) => void | Fires whenever the panel's dimensions change. |
onOpen | () => void | Fires when the panel opens. |
onClose | () => void | Fires on every close: the header close button, the launcher and Escape. |
onMessageAction | (event) => void | Fires when a visitor clicks a quick reply on a welcome message. |
className | string | Applied to the outer host element. |
style | React.CSSProperties | Inline styles for the outer host element. |
Do not unmount the widget in onClose. It fires on every close, so the launcher would disappear each time. Keep the component mounted.
Identifying a Visitor
To identify a visitor, pass a memoised user prop. Changing it re-runs the handshake. Setting it to undefined logs the visitor out:
<WexioWidget
publicKey="pk_live_..."
user={{ jwt: serverSignedJwt, name: "Ada Lovelace", email: "ada@example.com" }}
onOpen={() => analytics.track("widget_opened")}
/>Build the user object outside render or wrap it in useMemo. The widget keys its handshake on the proof, so a fresh object literal every render can re-trigger work.
Without an npm Install (ESM CDN)
If you can't add a dependency, load the React component from the CDN with an import map:
<script type="importmap">
{
"imports": {
"react": "https://esm.sh/react@19",
"react-dom": "https://esm.sh/react-dom@19",
"react-dom/client": "https://esm.sh/react-dom@19/client",
"react/jsx-runtime":"https://esm.sh/react@19/jsx-runtime"
}
}
</script>
<div id="widget-mount"></div>
<script type="module">
import { createElement } from "react";
import { createRoot } from "react-dom/client";
import { WexioWidget } from "https://cdn.wexio.io/widget/widget-react.js";
const root = createRoot(document.getElementById("widget-mount"));
root.render(createElement(WexioWidget, { publicKey: "pk_live_..." }));
</script>Server-Side Rendering
On the server the component renders only an empty host div. The widget appears after hydration, so it is safe in SSR frameworks. In the Next.js App Router, render it from a component marked "use client".
Upgrading to 1.8.0
Props, callbacks and types are unchanged. setWexioPublicKey still exists so old code compiles, but it does nothing now: the widget takes the key from publicKey.
Try It Live
The examples repo has a runnable React (Vite) example. You can also configure the widget live in the Playground.
Related
- Authentication - produce a
VisitorIdentityproof. - Theming with config - pass a
themevia theconfigprop. - API reference - full prop list and types.
- Examples - runnable apps for every framework.