Marketrix Widget

The embeddable Marketrix support widget. Drop it into any web page and your users get an in-product assistant that can Tell them how something works, Show them step-by-step with on-page highlighting, or Do the task for them in the browser.

Published to npm as @marketrix.ai/widget. Ships as a single ES module (widget.mjs) plus a classic loader.js bootstrap.

React 19 is required. The widget treats react and react-dom as peer dependencies and does not bundle them — the host page must provide React 19. The script-tag loader injects a React 19 importmap for you; npm consumers already have React in their app.

Install

There are two integration paths. Most sites should use the script tag — it's the simplest and provides React for you.

1. Script tag (recommended)

Add one <script> to your page <head>, before any <script type="module"> tags (the loader installs the React importmap that your module scripts rely on):

<script
  src="https://widget.marketrix.ai/loader.js"
  mtx-id="your-marketrix-id"
  mtx-key="your-marketrix-key"
  mtx-api-host="https://api.marketrix.ai"
></script>

loader.js:

Injects a React 19 importmap (defaults to esm.sh/react@19). If your page already has an importmap, the loader merges it and your mappings win — so a host that already ships React 19 keeps its own copy.
Injects <script type="module" src=".../widget.mjs"> from the same origin as the loader.
Forwards every mtx-* attribute from the loader tag to the widget.

The widget then auto-initializes from those attributes — no extra JavaScript required.

2. npm / programmatic

npm install @marketrix.ai/widget
# react@^19.2.3 and react-dom@^19.2.3 must already be installed in your app

import { mountWidget } from '@marketrix.ai/widget';

await mountWidget({
  mtxId: 'your-marketrix-id',
  mtxKey: 'your-marketrix-key',
  mtxApiHost: 'https://api.marketrix.ai',
});

mountWidget auto-detects the credential mode (production / dev / preview) from the config you pass.

Credential modes

The widget supports three modes, auto-detected from the credentials you provide.

Mode	Credentials	Script attributes	Network
Production	`mtxId` + `mtxKey`	`mtx-id` + `mtx-key`	Fetches settings from the API, opens the live stream
Dev	`mtxApp` (application id) + `mtxAgent` (agent id)	`mtx-app` + `mtx-agent`	Same as production, keyed by ids instead of credentials
Preview	`settings` object passed in code	—	No network — renders appearance only from the supplied settings

All modes also accept the common options below.

Configuration options

These apply to every mode (script attribute → config key):

Config key	Script attribute	Type	Description
`mtxApiHost`	`mtx-api-host`	string	API server URL, e.g. `https://api.marketrix.ai`. The widget has no baked-in API host — you must supply it.
`container`	—	`HTMLElement`	Element to mount inside (programmatic only). Defaults to a container appended to `<body>`.
`userId`	—	number	Associates widget activity with one of your users.
`show_widget`	—	boolean	When `false`, the widget initializes fully but its UI stays hidden. Default `true`.
`use_screenshare`	`mtx-use-screenshare`	boolean	When `false`, screen-share requests are auto-denied and the Share Screen button is hidden. Default `true`. Disable via `mtx-use-screenshare="false"`.

Widget appearance and behavior (position, colors, sizing, border radius, animation, enabled Tell/Show/Do/Human features, device visibility, header/body/greeting text, and quick-action chips) are configured in the Marketrix dashboard and fetched from the API at init. You don't set them in the embed — except in preview mode, where you pass them inline as settings.

Full script-tag example

<!doctype html>
<html>
  <head>
    <script
      src="https://widget.marketrix.ai/loader.js"
      mtx-id="your-marketrix-id"
      mtx-key="your-marketrix-key"
      mtx-api-host="https://api.marketrix.ai"
      mtx-use-screenshare="false"
    ></script>
  </head>
  <body>
    <!-- your app -->
  </body>
</html>

The loader takes care of the React 19 importmap. If you manage your own importmap, place it before the loader and the loader will merge (and defer to) it:

<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>
<script src="https://widget.marketrix.ai/loader.js" mtx-id="..." mtx-key="..." mtx-api-host="..."></script>

Programmatic API

All functions are named exports of @marketrix.ai/widget (also available on the default export).

import {
  mountWidget,
  initWidget,
  unmountWidget,
  updateMarketrixConfig,
  getCurrentConfig,
  startRecording,
  stopRecording,
  getRecordingState,
  MarketrixWidget,
} from '@marketrix.ai/widget';

`mountWidget(config): Promise<void>`

Auto-detects the mode (preview / production / dev) from config and initializes the widget. The recommended entry point for programmatic use.

// Production
await mountWidget({ mtxId, mtxKey, mtxApiHost });

// Dev
await mountWidget({ mtxApp: 123, mtxAgent: 456, mtxApiHost });

// Preview (no network — just renders the appearance)
await mountWidget({ settings: { widget_enabled: true, widget_position: 'bottom_right' /* ... */ } });

`initWidget(config, container?): Promise<void>`

Lower-level production/dev initializer. Validates credentials, fetches settings from the API, mounts into a closed Shadow DOM, opens the event stream, and starts session recording once a chat id exists. Optionally mounts inside a specific container. Concurrent and duplicate calls are deduplicated; only one production widget runs per page.

await initWidget({ mtxId, mtxKey, mtxApiHost }, document.getElementById('my-container')!);

`unmountWidget(): void`

Destroys the widget, stops session recording, closes the stream connection, and cleans up all resources.

`updateMarketrixConfig(partial): Promise<void>`

Merges partial into the current config and re-initializes (unmount + initWidget). Use to switch API host, credentials, etc. at runtime.

`getCurrentConfig(): MarketrixConfig | null`

Returns the active configuration, or null if the widget isn't initialized.

Session recording

The widget records user sessions (via rrweb) automatically once initialized. These helpers let you control it:

startRecording(): Promise<void> — start or resume recording. Throws if the widget wasn't initialized with mtxApiHost and an application (mtxApp).
stopRecording(): void — pause recording without unmounting the widget.
getRecordingState(): boolean — whether recording is currently active.