@ragnarokai/react-assistant-widget

React provider and hook for the Ragnarok assistant embed (assistant-widget.js and variants). Use them to load the script, initialize the floating widget, and drive conversation context (the same postMessage flow as AssistantWidget.setContext / resetContext).

Install

npm install @ragnarokai/react-assistant-widget

Peer dependency: React 18+.

Usage

widgetOrigin (Ragnarok app URL)

widgetOrigin must be the origin of the deployment that serves /scripts/*.js (see below), /api/public/widget-embed-config/{assistantId}, and /widget/assistants/... (no trailing slash; it is normalized).

Same-origin apps (for example your Ragnarok Next.js app wrapping pages with the provider) may omit widgetOrigin. In the browser the provider then uses window.location.origin, so you only need assistantId plus any UI overrides.

Third-party sites (customer domains, iframes, or any host that is not that Ragnarok origin) must pass widgetOrigin explicitly.

Dashboard defaults and overrides

When assistantId is set and widgetOrigin is resolved, the provider fetches merged UI defaults from:

{widgetOrigin}/api/public/widget-embed-config/{assistantId}

Those values reflect the Assistant → Widget settings saved in the dashboard. Any prop you pass (for example position, launcherSize, headerTitle) overrides that key only; omit a prop to keep the saved default.

Embed bundles under {widgetOrigin}/scripts/:

| File | Default widgetOrigin when omitted in vanilla init (per script) | |------|---------------------------------------------------------------------| | assistant-widget.js | https://ragnarokai.io | | dev-assistant-widget.js | https://dev.ragnarokai.io | | local-assistant-widget.js | http://localhost:3000 |

The React provider loads embed-config first, then picks the script from saved widgetScriptFile (or your scriptUrl / widgetScriptFile props). If none apply, it uses assistant-widget.js.

scriptUrl is optional. Pass an absolute URL to override the script host or filename. Otherwise the provider builds {widgetOrigin}/scripts/{widgetScriptFile} (default file: assistant-widget.js).

Pass scriptUrl when the script is hosted somewhere else (for example a CDN).

Option A — single config object

import {
  AssistantWidgetProvider,
  useAssistantWidget,
} from "@ragnarokai/react-assistant-widget";

const WIDGET_ORIGIN = "https://ragnarokai.io";

function App() {
  return (
    <AssistantWidgetProvider
      config={{
        assistantId: "YOUR_ASSISTANT_ID",
        widgetOrigin: WIDGET_ORIGIN,
        position: "bottom-right",
        launcherSize: 64,
      }}
    >
      <MyPage />
    </AssistantWidgetProvider>
  );
}

Option B — same fields as top-level props

Every option supported by AssistantWidget.init can be passed as a React prop (do not pass both config and duplicate fields). assistantId is required. widgetOrigin is optional on same-origin pages (see above).

<AssistantWidgetProvider
  assistantId="YOUR_ASSISTANT_ID"
  widgetOrigin={WIDGET_ORIGIN}
  position="bottom-left"
  bottom={24}
  left={24}
  launcherSize={56}
  panelWidth={280}
  panelHeight={400}
  borderRadius={12}
  zIndex={999999}
  toggle
  state="closed"
  backgroundColor="#111827"
  iconUrl="https://example.com/icon.png"
>
  <MyPage />
</AssistantWidgetProvider>

Minimal same-origin shell

<AssistantWidgetProvider assistantId="YOUR_ASSISTANT_ID">
  <MyPage />
</AssistantWidgetProvider>

Declarative externalContext

Pass externalContext on the provider to keep the iframe in sync with React state. Omit the prop if you only use the hook. Pass null to clear context.

function MyPage() {
  const { setContext, resetContext, ready } = useAssistantWidget();

  return (
    <button
      type="button"
      disabled={!ready}
      onClick={() => setContext("User is viewing the billing page.")}
    >
      Attach page context
    </button>
  );
}

When layout-related props change, the provider tears down the embed and runs init again with the new values. Use the externalContext, welcomeMessage, and quickActions props (or the hook) for live updates without remounting for layout-only tweaks.

Visitor object (persisted chats)

When persistConversations is enabled, pass a visitor object so conversations are keyed to your user and show up in assistant logs:

<AssistantWidgetProvider
  assistantId="YOUR_ASSISTANT_ID"
  persistConversations
  visitor={{
    id: user.id,
    name: user.name,
    avatar: user.picture,
    plan: "pro",
  }}
>
  <MyPage />
</AssistantWidgetProvider>

Canonical keys: id (storage partition), name, avatar (HTTPS URL). Any additional keys are stored and visible in log tooltips.

Welcome message and quick actions

Saved assistant settings can include a welcome message and quick-action chips. Pass them on init or declaratively on the provider:

<AssistantWidgetProvider
  assistantId="YOUR_ASSISTANT_ID"
  welcomeMessage="Hi! Ask me about your account."
  quickActions={[
    { label: "Billing", prompt: "How do I update my payment method?" },
    { label: "Support", prompt: "I need help with an order." },
  ]}
>
  <MyPage />
</AssistantWidgetProvider>

After the widget is ready, use the hook for runtime updates (same as AssistantWidget.setWelcomeMessage / setQuickActions on the embed script):

const {
  setWelcomeMessage,
  resetWelcomeMessage,
  setQuickActions,
  addQuickAction,
  removeQuickAction,
  resetQuickActions,
} = useAssistantWidget();

Pass null on the provider for welcomeMessage or quickActions to reset to defaults / clear chips.

Publish to npm

1. Create the @ragnarokai scope on npmjs.com (or use an org you control).

2. Log in: npm login

3. From this directory:

   npm run build
   npm publish --access public

Scoped packages default to restricted; --access public is required for open source installs.

License

MIT