DIQWidgetHost

Last updated 8/05/2026

Overview

React component for embedding the

DimensionIQWidget

into a React component.

DIQWidgetHost

manages:

• Widget rendering
• Connection lifestyle
• Event handling
• Callback synchronization
• Imperative widget commands

Use this component when integrating the

DimensionIQWidget

into a React application.

DIQWidgetHost

provides a React-native integration layer around the

DimensionIQWidget

.

Integration is primarily callback-driven:

• Use
  sendCommand()
  to control the widget
• Use callbacks to handle widget events
• Use
  onResponse()
  to confirm persistence or validation operations

Quick Start

import { useRef } from 'react';
import DIQWidgetHost, {
  type DIQWidgetHostHandle,
} from './DIQWidgetHost';

function MyPage() {
  const widgetRef = useRef<DIQWidgetHostHandle>(null);

  return (
    <div style={{ width: 1200, height: 800 }}>
      <DIQWidgetHost
        ref={widgetRef}
        iframeURL='https://www.dimensioniq.com/control/{build}/iframe-widget/src/widget.php?key=DIQ-DEMO-0000-0000'

        onReady={() => {
          widgetRef.current?.sendCommand(
            'loadProject',
            myProject
          );
        }}

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

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

How Integration Works

There are two primary integration points:

1. Send Commands

Use the component ref to control the widget.

widgetRef.current?.sendCommand(
    'loadProject',
    projectPayload
);

Examples:

widgetRef.current?.sendCommand(
  'setDimensionMode',
  'length'
);

widgetRef.current?.sendCommand(
  'setMeasurementSystem',
  'imperial'
);

widgetRef.current?.sendCommand(
  'clearDimensions'
);

2. Handle Callbacks

Callbacks are how your application receives updates from the widget.

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. Render
   DIQWidgetHost
   .
2. Handle updates via callbacks.
3. Persist updates to your backend.
4. Component unmount handles cleanup automatically.

Best Practices

• Treat callbacks as your source of truth
• Always call
  onResponse()
  when provided
• Keep persistence logic inside callbacks
• Use refs for imperative widget control

API Reference

Component

<DIQWidgetHost />

Props

Required Props

Prop	Type	Description
iframeURL	string	Full widget URL including ?key=YOUR_KEY .
callbacks	DimensionIQWidgetCallbacks	Widget event handlers.

Optional Props

Prop	Type	Description
widgetOrigin	string	Overrides the expected widget origin.
style	React.CSSProperties	Styles applied to the outer container.
showStatus	boolean	Displays connection status overlay.
verbose	boolean	Enables debug logging.
readyTimeout	number	Widget initialization timeout in milliseconds.
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.