React bindings
Integrate the Mojar widget into a React app using @mojar/sdk-react or the loader script.
There are two ways to embed the Mojar widget in a React application. The loader script approach is the confirmed, production-tested method and works inside React apps without any package installation. The @mojar/sdk-react package is the intended npm-based alternative for apps that prefer component-driven integration.
Option 1 — Loader script inside React (confirmed)
You can use the loader script in any React app by injecting the <script> tag once on mount. This works with React 18+, Next.js, Vite, Create React App, and any other bundler.
import { useEffect } from "react";
interface MojarWidgetProps {
agentId: string;
domainUuid: string;
}
export function MojarWidget({ agentId, domainUuid }: MojarWidgetProps) {
useEffect(() => {
// Bail out if already loaded (e.g. HMR / strict mode double-invoke)
if (window.MojarAIWidget) return;
const script = document.createElement("script");
script.src = "https://app.mojar.ai/widget-mojar-loader.js";
script.dataset.agentid = agentId;
script.dataset.domainuuid = domainUuid;
document.body.appendChild(script);
return () => {
// Tear down cleanly when the component unmounts
window.MojarAIWidget?.destroy();
};
}, [agentId, domainUuid]);
return null;
}Then mount it once in your application shell:
import { MojarWidget } from "./MojarWidget";
export default function App() {
return (
<>
{/* rest of your app */}
<MojarWidget
agentId="YOUR_AGENT_UUID"
domainUuid="YOUR_DOMAIN_UUID"
/>
</>
);
}You can interact with the widget imperatively via window.MojarAIWidget.open(), .close(), and .toggle() from anywhere in your component tree.
In React Strict Mode, useEffect runs twice in development. The window.MojarAIWidget guard above prevents the script being appended twice. In production Strict Mode does not double-invoke effects.
Option 2 — @mojar/sdk-react package
The @mojar/sdk-react package provides React component bindings for the widget.
Install
npm install @mojar/sdk-react
# peer dependency
npm install @mojar/sdkIntended usage
The package is expected to export a component (or provider + hook pair) that accepts the same identifiers as the loader script:
// TODO(verify): confirm the actual export name and prop names from @mojar/sdk-react
import { MojarProvider, MojarWidget } from "@mojar/sdk-react";
export default function App() {
return (
<MojarProvider agentId="YOUR_AGENT_UUID" domainUuid="YOUR_DOMAIN_UUID">
{/* rest of your app */}
<MojarWidget />
</MojarProvider>
);
}Choosing between the two approaches
| Loader script | @mojar/sdk-react | |
|---|---|---|
| Install required | No | Yes |
| Works in Next.js App Router | Yes (useEffect / Server Component boundary) | Not yet documented |
| Works in Vite/CRA | Yes | Not yet documented |
| Imperative API | window.MojarAIWidget | Not yet documented |
| Type safety | Manual (extend Window) | Yes (bundled types) |
| Bundle impact | Zero (external script) | Minimal |
If you need to ship today, use the loader script approach — it is confirmed working in production. Check back once the @mojar/sdk-react package is published to npm for the component-native path.
TypeScript — extend the Window type
When using the loader script approach you may want to type the global API:
interface MojarAIWidgetAPI {
open(): void;
close(): void;
toggle(): void;
destroy(): void;
reinitialize(): void;
}
declare global {
interface Window {
MojarAIWidget?: MojarAIWidgetAPI;
MojarAIWidgetV2?: MojarAIWidgetAPI;
}
}