Widget API Reference

The widget ships as the npm package @marketrix.ai/widget. Use it when you need programmatic control over the widget lifecycle. React 19 is a peer dependency.

npm install @marketrix.ai/widget

Script-tag install

For non-React sites, the classic loader needs no package install. The loader.js script injects the React import map, loads the widget bundle from the same origin, and passes through every mtx-* attribute.

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

Widget Setup covers where the loader must go on the page.

Script-tag attributes

Attribute	Type	Description
mtx-id	string	Your Widget ID.
mtx-key	string	Your Widget Key.
mtx-api-host	string	API server URL, e.g. https://api.marketrix.ai.
mtx-use-screenshare	boolean	Set to "false" to auto-deny screen-access requests and hide the Share Screen button.

Both mtx-id and mtx-key are required.

Functions

All functions are named exports of @marketrix.ai/widget.

initWidget(config, container?)

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

Validates credentials, fetches widget settings from the API, mounts the widget, and starts session recording. If container is omitted, the widget mounts to the page body. Concurrent and duplicate calls are deduplicated via a window-level singleton guard, so calling it twice is safe.

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

// Production
await initWidget({
  mtxId: 'YOUR_WIDGET_ID',
  mtxKey: 'YOUR_API_KEY',
  mtxApiHost: 'https://api.marketrix.ai',
});

// Mount into a specific container
await initWidget(config, document.getElementById('my-container')!);

mountWidget(config)

mountWidget(config: AddWidgetConfig): Promise<void>

Auto-detects the mode from the config and initializes the widget:

• Preview — settings provided directly (no network calls).
• Production — mtxId + mtxKey.

Throws if neither combination is present.

updateMarketrixConfig(newConfig)

updateMarketrixConfig(newConfig: Partial<MarketrixConfig>): Promise<void>

Merges newConfig into the current configuration, then unmounts and reinitializes the widget. No-op if the widget isn’t initialized; throws if the current config can’t be read.

getCurrentConfig()

getCurrentConfig(): MarketrixConfig | null

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

unmountWidget()

unmountWidget(): void

Destroys the widget, stops session recording, and removes the widget container. The live event stream is a page-level singleton and stays connected — reload the page to drop it.

Note

Session recording has no separate start/stop functions. It is driven entirely by the widget_recording dashboard setting — recording begins automatically once the widget registers its chat session, and unmountWidget() stops it.

React component (preview mode)

MarketrixWidget: React.FC<MarketrixWidgetProps>

Renders the widget into a parent container with its own Shadow DOM. Intended for preview/embedding inside a React app — it’s what the dashboard uses to render the live preview.

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

function Preview() {
  return (
    <MarketrixWidget
      settings={{ widget_enabled: true, widget_position: 'bottom_right' /* ...other settings */ }}
      mtxApiHost="https://api.marketrix.ai"
    />
  );
}

MarketrixWidgetProps

Prop	Type	Description
settings	WidgetSettingsData	Widget settings to render (required).
container	HTMLElement	Optional element to mount into; defaults to the component’s own div.
mtxId	string	Optional credential override.
mtxKey	string	Optional credential override.
mtxApiHost	string	Optional API host override.

Configuration: MarketrixConfig

MarketrixConfig is Partial<WidgetSettingsData> plus the fields below. In production mode the settings fetched from the API are merged over your config, so any WidgetSettingsData key passed inline is replaced by the dashboard value — those keys only take effect in preview mode, where you supply settings yourself.

Key	Type	Description
mtxId	string	Widget ID.
mtxKey	string	Widget Key.
mtxApiHost	string	API server URL.
userId	number	Optional user ID to associate with widget questions.
widget_position_z_index	number	Stacking order. Raised to the widget’s own layer (2147483002) if you pass anything lower, so it can only move the widget higher.
show_widget	boolean	When false, the widget initializes fully but its UI is hidden. Default true.
use_screenshare	boolean	When false, screen-access requests are auto-denied and the Share Screen button is hidden. Default true.
isPreviewMode	boolean	Marks the widget as a non-networked preview instance.

Production mode needs mtxId, mtxKey, and mtxApiHost — there is no default API host. Preview mode supplies settings directly, makes no network calls, and needs none of the three.

Settings keys: WidgetSettingsData

These are the dashboard-managed appearance and behavior settings. They’re returned by the API for a production widget and can be supplied inline in preview mode.

Key	Type	Notes
widget_enabled	boolean	Master on/off.
widget_appearance	'default' | 'hidden'	hidden keeps the widget initialized but suppresses its UI on the host page.
widget_position	'bottom_left' | 'bottom_right' | 'top_left' | 'top_right'	Corner placement.
widget_header	string	Header title.
widget_body	string	Intro/body text.
widget_greeting	string	The widget’s first message.
widget_greeting_toast	boolean	Show the welcome toast. Independent of the greeting message in chat.
widget_recording	boolean	Enable rrweb session recording. Off by default.
widget_feature_tell	boolean	Enable Tell mode.
widget_feature_show	boolean	Enable Show mode.
widget_feature_do	boolean	Enable Do mode.
widget_background_color	string
widget_text_color	string
widget_border_color	string
widget_accent_color	string
widget_secondary_color	string
widget_border_radius	string	e.g. 16px.
widget_font_size	string
widget_width	string
widget_height	string
widget_animation_duration	string
widget_fade_duration	string
widget_chips	WidgetChip[]	Quick-action chips.

A WidgetChip is { chip_mode: 'tell' \| 'show' \| 'do'; chip_text: string }.

Example: full lifecycle

import { initWidget, updateMarketrixConfig, unmountWidget } from '@marketrix.ai/widget';

// Initialize after the user logs in
await initWidget({
  mtxId: 'YOUR_WIDGET_ID',
  mtxKey: 'YOUR_API_KEY',
  mtxApiHost: 'https://api.marketrix.ai',
});

// Hide the widget on a full-screen route
await updateMarketrixConfig({ show_widget: false });

// Tear down on logout
unmountWidget();

Keep the Widget Key out of source you ship publicly — see Keeping your key safe.