DIQWidgetConfig

Last updated 22/07/2026

Overview

DIQWidgetConfig

controls the runtime behavior and startup configuration of the

DimensionIQWidget

.

It allows the host application to configure how the widget starts, customize portions of the user interface, enable optional runtime features, and declare which operations are managed directly by the host application.

DIQWidgetConfig

is supported by both:

• DIQWidgetHost
  (React)
• DIQWidgetBridge
  (Vanilla JavaScript)

The widget configuration is supplied when the widget is created and may also be updated at runtime using

applyConfig()

.

Example

import type { DIQWidgetConfig } from 'dimensioniq';

const config: DIQWidgetConfig = {

    // Automatically open a project
    initialProjectKey: 'project-001',

    // Hide the Project menu
    showProjectMenu: false,

    // Hide the DimensionIQ logo
    hideLogo: true,

    // Host controls selected workflows
    capabilities: {
        openProject: true,
        createRevision: true
    },

    // Combine mutation callbacks
    enableBatching: true
};

Configuration Properties

Property	Description
initialProjectKey	Automatically opens a project when the widget loads
showProjectMenu	Controls visibility of the Project menu, defaults to true
hideLogo	Hides the DimensionIQ logo from the toolbar, buttons automatically shift left to occupy the available space
capabilities	Declares which widget workflows are managed by the host application, see DIQCapabilities for further information
enableBatching	Combines multiple mutation callbacks generated during batch operations into a single onBatchUpdate callback, defaults to false

Using initialProjectKey

When

initialProjectKey

is supplied, the widget automatically requests the project from the host application during startup.

To support this behavior, 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()

must be called exactly once.

Callbacks that receive an

onResponse()

function are part of the widget request lifecycle. The widget waits until

onResponse()

is invoked before continuing.

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
);

Using showProjectMenu

By default, the widget displays a Project menu that provides access to project management functions.

Setting

showProjectMenu

to

false

hides this menu.

This is useful when the host application already provides its own project selection or navigation interface.

Example

const config = {

    showProjectMenu: false

};

Using hideLogo

Setting

hideLogo

to

true

removes the DimensionIQ logo from the toolbar.

The remaining toolbar buttons automatically shift left to occupy the available space.

This is commonly used when embedding the widget into applications with their own branding.

Example

const config = {

    hideLogo: true

};

Using capabilities

The

capabilities

property allows the host application to take ownership of selected widget workflows.

When a capability is enabled, the corresponding widget user interface is hidden and the host application becomes responsible for initiating that workflow through the widget API.

This prevents duplicate controls when the host application already provides its own project, drawing, or revision management interface.

For the complete list of supported capabilities, see

DIQCapabilities

.

Example

const config = {

    capabilities: {

        openProject: true,
        newProject: true,
        createRevision: true

    }

};

Using enableBatching

Normally, every modification made by the widget immediately generates its corresponding callback.

When

enableBatching

is enabled, callbacks generated within a batched operation are buffered and delivered together as a single

onBatchUpdate

callback.

This can significantly reduce callback traffic during operations that create, update, or remove many objects.

Example

const config = {

    enableBatching: true

};

When batching is enabled, the host application should also implement

callbacks.onBatchUpdate

.

If

onBatchUpdate

is not implemented, batched mutations are discarded rather than replayed as individual callbacks.

React - DIQWidgetHost

config

is supplied directly to the

DIQWidgetHost

component and may be used together with

theme

.

Example

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

The configuration is transmitted during the initial widget connection handshake.

If the configuration changes after the widget has connected, the updated values are not automatically transmitted. To apply updated configuration values, remount or reconstruct the component.

Vanilla JavaScript - DIQWidgetBridge

config

may also be supplied when constructing

DIQWidgetBridge

.

Example

const bridge = new DIQWidgetBridge({

    container: document.getElementById('widget-container'),

    iframeURL: 'https://...',

    callbacks,

    config

});

The configuration is transmitted once during the initial ready handshake.

Runtime Updates

DIQWidgetBridge

supports updating the widget configuration while the widget is running.

Example

bridge.sendCommand('applyConfig', updatedConfig);

All configuration properties except

initialProjectKey

may be updated dynamically.

Updating

initialProjectKey

after the widget has loaded does not automatically open another project. To open a different project after startup, use the appropriate project API instead.