DIQWidgetConfig

Last updated 8/05/2026

Overview

The

DimensionIQWidget

supports extensive visual customization and runtime configuration through:

• DIQTheme
  - controls appearance and branding
• DIQWidgetConfig
  - controls widget behavior

Both options are supported by:

• DIQWidgetHost
  (React)
• DIQWidgetBridge
  (Vanilla JavaScript)

DIQWidgetConfig Example

DIQWidgetConfig

controls widget behavior and startup configuration.

import type { DIQWidgetConfig } from 'dimensioniq';

const myConfig: DIQWidgetConfig = {
    /**
     * Automatically opens a project when the widget loads.
     */
    initialProjectKey: 'your-project-key',

    /**
     * Hides the Project menu button when false.
     */
    showProjectMenu: false
};

Configuration Properties

Property	Description
initialProjectKey	Automatically opens a project when the widget loads
showProjectMenu	Controls visibility of the Project menu button

Using initialProjectKey

When the

initialProjectKey

is supplied, the widget automatically requests the project from the host application during startup. To support this workflow, the host application must implement the

onProjectGet

callback.

Example

callbacks: {
    onProjectGet(projectKey, onResponse) {
        const project = myDatabase.getProject(projectKey);

        if (project) {
            onResponse(
                { ok: true, message: '' },
                project
            );
        } else {
            onResponse(
                { ok: false, message: `Project ${projectKey} not found` },
                null
            );
        }
    },
}

Important

onResponse()

is required.

Callbacks that receive an

onResponse()

function are part of the widget request lifecycle. The host application must call

onResponse()

exactly once after the operation completes. If

onResponse()

is never called, the widget remains in a pending state and cannot continue its internal workflow.

Successful Response

onResponse(
    { ok: true, message: '' },
    project
);

Failed Response

onResponse(
    { ok: false, message: 'Project not found' },
    null
);

React - DIQWidgetHost

config

is passed directly to the widget host component. It can be used in conjunction with

theme

.

<DIQWidgetHost
    iframeURL="https://..."
    callbacks={callbacks}
     config={myConfig}  
/>

The value is transmitted during the initial widget connection handshake. If the value changes after connection, the updated value is not automatically re-sent. To apply updated values, remount or reconstruct the host component.

Vanilla JS - DIQWidgetBridge

theme

can also be supplied when constructing

DIQWidgetBridge

. It can be used in conjunction with

theme

.

const bridge = new DIQWidgetBridge({
    container: document.getElementById('widget-container'),
    iframeURL: 'https://...',
    callbacks,
    config: myConfig
});

The value is sent once during the initial ready handshake.

Runtime Updates

DIQWidgetBridge

supports runtime updates using

sendCommand()

Apply a New Config

bridge.sendCommand('applyConfig', myUpdatedConfig);