DIQWidgetBridge

Last updated 7/05/2026

Embed the

DimensionIQWidget

and integrate it into your application using a callback-driven SDK.

Overview

DIQWidgetBridge

lets you:

• Embed the widget in your app
• Send commands to control it
• Handle user actions via callbacks
• Sync widget data with your backend

Integration is primarily done through callbacks.

Quick Start

import { DIQWidgetBridge } from './DIQWidgetBridge';

const bridge = new DIQWidgetBridge({
  container: document.getElementById('widget-container')!,
  iframeURL: 'https://www.dimensioniq.com/control/{build}/iframe-widget/src/widget.php?key=DIQ-DEMO-0000-0000',

  onReady: () => {
    bridge.sendCommand('loadProject', myProject);
  },

  callbacks: {
    onDimensionsNew: (dimensions: Array<DIQ_Dimension>, onResponse: (result: DIQ_Result) => void) => {
      saveToDB(dimensions).then(() => onResponse({ ok: true }));
    },
  },
});

How Integration Works

There are only two things you need to wire up:

1. Send Commands

You control the widget using:

bridge.sendCommand('action', ...args);

Typical example:

bridge.sendCommand('loadProject', projectPayLoad);

2. Handle Callbacks

The widget notifies your app through callbacks.

callbacks: {
  onDimensionsNew: (dimensions: Array<DIQ_Dimension>, onResponse: (result: DIQ_Result) => void) => {
    saveToDB(dimensions).then(() => onResponse({ ok: true }));
  }
}

Responding to Events

onResponse()

must always be called once the host application has finished processing the event.

onDimensionsNew: (dimensions: Array<DIQ_Dimension>, onResponse: (result: DIQ_Result) => void) => {
  saveToDB(dimensions)
    .then(() => onResponse({ ok: true }))
    .catch(() => onResponse({ ok: false }));
}

Typical Integration Flow

1. Create the bridge.
2. Wait for
   onReady
   .
3. Handle updates via callbacks.
4. Persist data to your backend.
5. Clean up when done.

Lifecycle Management

Always clean up:

bridge.destroy();

Common Pattern: Persisting Data

callbacks: {
  onDimensionsNew: (dimensions: Array<DIQ_Dimension>, onResponse: (result: DIQ_Result) => void) => {
    saveToDB(dims)
      .then(() => onResponse({ ok: true }))
      .catch(() => onResponse({ ok: false }));
  },

  onDimensionUpdate: (dimension: DIQ_Dimension, onResponse: (result: DIQ_Result) => void) => {
    updateInDB(dim)
      .then(() => onResponse({ ok: true }))
      .catch(() => onResponse({ ok: false }));
  }
}

Best Practices

• Initialize your project inside
  onReady
• Treat callbacks as your source of truth
• Always call
  onResponse()
  when required
• Keep backend logic inside callbacks
• Call
  destroy()
  on teardown

API Reference

Constructor

new DIQWidgetBridge(options: DIQWidgetBridgeOptions)

DIQWidgetBridgeOptions

Required

Field	Type	Description
container	HTMLElement	Element that will host the widget. Must have a defined size.
iframeURL	string	Full widget URL including ?key=YOUR_KEY .

Optional

Field	Type	Description
callbacks	Partial<Callbacks>	Event handlers from the widget.
onReady	() => void	Called once when the widget is ready.
onTimeout	() => void	Called if initialization times out.
onError	(err:Error) => void	Called if the widget fails to load.
readyTimeout	number	Widget initialization timeout in milliseconds.
verbose	boolean	Enables debug logging.
theme	DIQTheme	Theme used to customize the widget appearance. Sent to the widget once connected. Omitted values fall back to the DimensionIQ defaults.
config	DIQWidgetConfig	Behavioral configuration for the widget. Sent to the widget once connected.

Methods

sendCommand

sendCommand(action: string, ...args: any[]): void

Sends a command to the widget.

Examples

bridge.sendCommand('loadProject', projectPayload);
bridge.sendCommand('setDimensionMode', 'length');
bridge.sendCommand('setMeasurementSystem', 'imperial');

setCallbacks

setCallbacks(callbacks: Callbacks): void

Replaces all callbacks after initialization.

destroy

destroy(): void

Removes the widget and cleans up resources.

Error Handling

• onTimeout
  - widget didn't initialize in time
• onError
  - iframe failed to load
• onResponse({ ok: false })
  - operation failed

Lifecycle Summary

Stage	Action
Initialize	new DIQWidgetBridge()
Ready	onReady fires
Operate	sendCommand + callbacks
Cleanup	destroy()