Create a Static Custom Item for the Web Dashboard

Sep 01, 2025
7 minutes to read

Important

A custom item is an independent module called an extension. If you are not familiar with the basic concepts of extensions, please review the following topic before you continue: Extensions Overview.

This tutorial shows how to create a custom item that displays text and adds a custom property that allows you to change this static text in the UI.

You can download the ready-to-use projects based on the Create a custom item tutorials:

View Example: ASP.NET Core View Example: React

Prerequisites

A custom item script depends on the platform you use:

Module scriptClient components (Angular, React, Vue) use imports and classes to define a custom item.Classic scriptA script for the ASP.NET Web Forms, ASP.NET MVC, ASP.NET Core, BLazor, and JavaScript controls encapsulates a custom item in the IIFE function expression.

Before you begin, create a Web Dashboard project for the required platform.

Create an External Script

In your project, create an external HelloWorldItem.js file, so you can reuse the created extension in other Web Dashboard applications.

Define a class that will be a custom item (HelloWorldItem).

Module
Classic

import { CustomItemViewer, ResourceManager } from 'devexpress-dashboard/common'
import { CustomItem } from 'devexpress-dashboard/model'
class HelloWorldItem {
}

export default HelloWorldItem;

window.HelloWorldCustomItem = (function () {
    class HelloWorldItem {
    }
    return HelloWorldItem;
})();

Warning

If you use the Classic script, place the code below inside the self-invoking function.

Define a Toolbox Icon

In the HelloWorldItem.js file, add a 24x24 SVG icon as a string variable:

Module
Classic

var svgIcon = '<svg id="helloWorldItemIcon" viewBox="0 0 24 24"><path stroke="#42f48f" fill="#42f48f" d="M12 2 L2 22 L22 22 Z" /></svg>';

const svgIcon = '<svg id="helloWorldItemIcon" viewBox="0 0 24 24"><path stroke="#42f48f" fill="#42f48f" d="M12 2 L2 22 L22 22 Z" /></svg>';

The icon will be used later to display the custom item in the Toolbox:

Specify the Custom Item’s Settings

Implement the ICustomItemMetaData interface to define this custom item’s settings:

In the icon option, pass the SVG icon’s id (helloWorldItemIcon).
In the title option, specify the text displayed in the dashboard item caption and as the Toolbox element’s tooltip (Hello World Item).

Use the ICustomItemMetaData.customProperties and ICustomItemMetaData.optionsPanelSections properties to define a custom option that allows a user to change the custom dashboard item’s display text:

Create the CustomPropertyMetadata object and define a string customProperty option. Add the created option to the ICustomItemMetaData.customProperties collection.
Create the SectionOptions object that defines a new Custom Properties section in the dashboard item’s Options menu. The SectionOptions.items collection contains editors used to manage custom property values in the UI. Define dxTextBox as an editor. Add the created option to the ICustomItemMetaData.optionsPanelSections collection.

Module
Classic

var helloWorldItemMetaData = {
    customProperties: [{
        ownerType: CustomItem,
        propertyName: 'customProperty',
        valueType: 'string',
        defaultValue: 'Hello World!'
    }],
    optionsPanelSections: [{
        title: 'Custom Properties',
        items: [{
            dataField: 'customProperty',
            label: {
                text: 'Item Text'
            },
            editorType: 'dxTextBox',
            editorOptions: {
                placeholder: "Enter text to display"
            }
        }]
    }],
    icon: 'helloWorldItemIcon',
    title: 'Hello World Item'
};

const helloWorldItemMetaData = {
    customProperties: [{
        ownerType: DevExpress.Dashboard.Model.CustomItem,
        propertyName: 'customProperty',
        valueType: 'string',
        defaultValue: 'Hello World!'
    }],
    optionsPanelSections: [{
        title: 'Custom Properties',
        items: [{
            dataField: 'customProperty',
            label: {
                text: 'Item Text'
            },
            editorType: 'dxTextBox',
            editorOptions: {
                placeholder: "Enter text to display"
            }
        }]
    }],
    icon: 'helloWorldItemIcon',
    title: 'Hello World Item'
};

Implement Custom Item Rendering

The CustomItemViewer class specifies visual representation of the custom item. Override the CustomItemViewer.renderContent method to display custom item content. Use the CustomItemViewer.getPropertyValue method to get the value of the created custom option and display this value in the viewer.

Note

Do not set IDs for DOM elements in the CustomItemViewer.renderContent method call. When the custom item is maximized, the renderContent method is called again and creates one more DOM element with the same ID. If you create an element inside this method, the element ID will not be unique on the page.

Module
Classic

import { CustomItemViewer, ResourceManager } from 'devexpress-dashboard/common'
import { CustomItem } from 'devexpress-dashboard/model'
// ...
class HelloWorldItemViewer extends CustomItemViewer {
    renderContent(element, changeExisting) {
        element.innerText = this.getPropertyValue('customProperty');
    };
}

class HelloWorldItemViewer extends DevExpress.Dashboard.CustomItemViewer {
    constructor(model, $container, options) {
        super(model, $container, options);
    }
    renderContent = function ($element, changeExisting) {
        var element = $element.jquery ? $element[0] : $element;
        element.innerText = this.getPropertyValue('customProperty');
    }
}

Create an Extension

The ICustomItemExtension interface allows you to define a custom item as an extension.

Use the ResourceManager.registerIcon static method to register the custom item’s icon.
Pass the created metadata to the ICustomItemExtension.metaData property.
Specify the IExtension.name property. This property defines the custom item name in the dashboard definition. If you want to display the same dashboard on the Desktop, make sure that the names of the custom item extensions on the Desktop and Web match.
Call the ICustomItemExtension.createViewerItem method to implement the created custom item.
Module
Classic

import { CustomItemViewer, ResourceManager } from 'devexpress-dashboard/common'
import { CustomItem } from 'devexpress-dashboard/model'
// ...
class HelloWorldItem {
    constructor(dashboardControl) {
        ResourceManager.registerIcon(svgIcon);    
        this.name = "helloWorldItem";
        this.metaData = helloWorldItemMetaData;
    }

    createViewerItem(model, $element, content) {
        return new HelloWorldItemViewer(model, $element, content);
    }
}

export default HelloWorldItem;

class HelloWorldItem {
    constructor(dashboardControl) {
        DevExpress.Dashboard.ResourceManager.registerIcon(svgIcon);
        this.name = "helloWorldItem";
        this.metaData = helloWorldItemMetaData;
    }
    createViewerItem(model, $element, content) {
        return new HelloWorldItemViewer(model, $element, content);
    }
}
return HelloWorldItem;

The complete extension code:

Show code

Module
Classic

// #region imports
import { CustomItemViewer, ResourceManager } from 'devexpress-dashboard/common'
import { CustomItem } from 'devexpress-dashboard/model'
// #endregion
// #region svgIcon
var svgIcon = '<svg id="helloWorldItemIcon" viewBox="0 0 24 24"><path stroke="#42f48f" fill="#42f48f" d="M12 2 L2 22 L22 22 Z" /></svg>';
// #endregion
// #region metadata
var helloWorldItemMetaData = {
    customProperties: [{
        ownerType: CustomItem,
        propertyName: 'customProperty',
        valueType: 'string',
        defaultValue: 'Hello World!'
    }],
    optionsPanelSections: [{
        title: 'Custom Properties',
        items: [{
            dataField: 'customProperty',
            label: {
                text: 'Item Text'
            },
            editorType: 'dxTextBox',
            editorOptions: {
                placeholder: "Enter text to display"
            }
        }]
    }],
    icon: 'helloWorldItemIcon',
    title: 'Hello World Item'
};
// #endregion
// #region viewer
class HelloWorldItemViewer extends CustomItemViewer {
    renderContent(element, changeExisting) {
        element.innerText = this.getPropertyValue('customProperty');
    };
}
// #endregion
// #region createItem
class HelloWorldItem {
    constructor(dashboardControl) {
        ResourceManager.registerIcon(svgIcon);    
        this.name = "helloWorldItem";
        this.metaData = helloWorldItemMetaData;
    }

    createViewerItem(model, $element, content) {
        return new HelloWorldItemViewer(model, $element, content);
    }
}

export default HelloWorldItem;
// #endregion

window.HelloWorldCustomItem = (function () {
    // #region svgIcon
    const svgIcon = '<svg id="helloWorldItemIcon" viewBox="0 0 24 24"><path stroke="#42f48f" fill="#42f48f" d="M12 2 L2 22 L22 22 Z" /></svg>';
    // #endregion
    // #region metadata
    const helloWorldItemMetaData = {
        customProperties: [{
            ownerType: DevExpress.Dashboard.Model.CustomItem,
            propertyName: 'customProperty',
            valueType: 'string',
            defaultValue: 'Hello World!'
        }],
        optionsPanelSections: [{
            title: 'Custom Properties',
            items: [{
                dataField: 'customProperty',
                label: {
                    text: 'Item Text'
                },
                editorType: 'dxTextBox',
                editorOptions: {
                    placeholder: "Enter text to display"
                }
            }]
        }],
        icon: 'helloWorldItemIcon',
        title: 'Hello World Item'
    };
    // #endregion
    // #region viewer
    class HelloWorldItemViewer extends DevExpress.Dashboard.CustomItemViewer {
        constructor(model, $container, options) {
            super(model, $container, options);
        }
        renderContent = function ($element, changeExisting) {
            var element = $element.jquery ? $element[0] : $element;
            element.innerText = this.getPropertyValue('customProperty');
        }
    }
    // #endregion
    // #region createItem
    class HelloWorldItem {
        constructor(dashboardControl) {
            DevExpress.Dashboard.ResourceManager.registerIcon(svgIcon);
            this.name = "helloWorldItem";
            this.metaData = helloWorldItemMetaData;
        }
        createViewerItem(model, $element, content) {
            return new HelloWorldItemViewer(model, $element, content);
        }
    }
    return HelloWorldItem;
    // #endregion
})();

Register the Custom Item Extension

Attach the created HelloWorldItem.js script file to the page containing the Web Dashboard code. The external script you created is now available in the application.

You need to register the extension before the control is rendered. Refer to the following topics for information on how to get access to the DashboardControl instance and customize it before any element in the Web Dashboard control has been rendered:

Module
Classic

function onBeforeRender(e) { 
  var dashboardControl = e.component;
  dashboardControl.registerExtension(new DashboardPanelExtension(dashboardControl));
  dashboardControl.registerExtension(new HelloWorldItem(dashboardControl));
  // ...
}

razor

function onBeforeRender(dashboardControl) {
    dashboardControl.registerExtension(new DevExpress.Dashboard.DashboardPanelExtension(dashboardControl));
    dashboardControl.registerExtension(new HelloWorldCustomItem(dashboardControl));
    <!-- // ... -->
}

Result

Run the project and click the Hello World Item Toolbox item to add the custom item to the dashboard:

This action adds the custom item with the predefined ‘Hello World!’ text on its surface. Open the item’s Options menu and go to the Custom Properties section to change the displayed text:

In the next lesson, you will learn how to create a custom item that is bound to data, and how to display data from a data source.