# @openremote/or-dashboard-builder > OpenRemote Dashboard Builder Latest version **1.30.0** (published 2026-09-02) · AGPL-3.0-or-later license · 0 weekly downloads ## Install ```sh npm install @openremote/or-dashboard-builder pnpm add @openremote/or-dashboard-builder yarn add @openremote/or-dashboard-builder bun add @openremote/or-dashboard-builder ``` ## Health **Score 70/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 1.30.0 | | Published | 2026-09-02 | | First published | 2024-05-12 | | Weekly downloads | 0 | | License | AGPL-3.0-or-later | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 24 | | Unpacked size | 6.9 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | OpenRemote | | Maintainers | openremotedeveloper, wborn | ## Links - npm: https://www.npmjs.com/package/@openremote/or-dashboard-builder - npm.io page: https://npm.io/package/@openremote/or-dashboard-builder ## Dependencies (24) - [lit](https://npm.io/package/lit.md) ^3.3.1 - [moment](https://npm.io/package/moment.md) ^2.29.4 - [@lit/task](https://npm.io/package/@lit/task.md) ^1.0.3 - [gridstack](https://npm.io/package/gridstack.md) ^12.4.2 - [lodash.debounce](https://npm.io/package/lodash.debounce.md) ^4.0.8 - [lodash.throttle](https://npm.io/package/lodash.throttle.md) ^4.1.1 - [@openremote/core](https://npm.io/package/@openremote/core.md) 1.30.0 - [@openremote/rest](https://npm.io/package/@openremote/rest.md) 1.30.0 - [@openremote/model](https://npm.io/package/@openremote/model.md) 1.30.0 - [@openremote/or-map](https://npm.io/package/@openremote/or-map.md) 1.30.0 - [@openremote/or-icon](https://npm.io/package/@openremote/or-icon.md) 1.30.0 - [@material/data-table](https://npm.io/package/@material/data-table.md) ^9.0.0 - [@openremote/or-chart](https://npm.io/package/@openremote/or-chart.md) 1.30.0 - [@openremote/or-gauge](https://npm.io/package/@openremote/or-gauge.md) 1.30.0 - [@openremote/or-element](https://npm.io/package/@openremote/or-element.md) 1.30.0 - [@openremote/or-translate](https://npm.io/package/@openremote/or-translate.md) 1.30.0 - [@openremote/or-asset-tree](https://npm.io/package/@openremote/or-asset-tree.md) 1.30.0 - [@openremote/or-components](https://npm.io/package/@openremote/or-components.md) 1.30.0 - [@openremote/or-attribute-card](https://npm.io/package/@openremote/or-attribute-card.md) 1.30.0 - [@openremote/or-mwc-components](https://npm.io/package/@openremote/or-mwc-components.md) 1.30.0 - [@openremote/or-attribute-input](https://npm.io/package/@openremote/or-attribute-input.md) 1.30.0 - [@openremote/or-attribute-picker](https://npm.io/package/@openremote/or-attribute-picker.md) 1.30.0 - [@openremote/or-vaadin-components](https://npm.io/package/@openremote/or-vaadin-components.md) 1.30.0 - [@openremote/or-attribute-barchart](https://npm.io/package/@openremote/or-attribute-barchart.md) 1.30.0 ## Recent versions - 1.30.0 (latest) — 2026-09-02 - 1.31.0-snapshot.20260916130646 (snapshot) — 2026-09-16 - 1.31.0-snapshot.20260915122244 — 2026-09-15 - 1.31.0-snapshot.20260911091633 — 2026-09-11 - 1.31.0-snapshot.20260910125057 — 2026-09-10 - 1.31.0-snapshot.20260910120754 — 2026-09-10 - 1.31.0-snapshot.20260908130403 — 2026-09-08 - 1.31.0-snapshot.20260907094218 — 2026-09-07 - 1.31.0-snapshot.20260904133325 — 2026-09-04 - 1.31.0-snapshot.20260904115341 — 2026-09-04 - 1.31.0-snapshot.20260904102436 — 2026-09-04 - 1.31.0-snapshot.20260903144735 — 2026-09-03 - 1.31.0-snapshot.20260903135821 — 2026-09-03 - 1.31.0-snapshot.20260903081447 — 2026-09-03 - 1.31.0-snapshot.20260902153911 — 2026-09-02 - … 790 more at https://npm.io/package/@openremote/or-dashboard-builder/versions ## README # or-dashboard-builder ### All-in-one bundle for creating dashboards with OpenRemote data. This component is the core of the Insights page on our OpenRemote manager,
where users can build dashboards with widgets, for monitoring their assets in their preferred way.
It is quite an extensive piece of code, so some apps using this (such as or standalone Insights app)
might not need the full package.

It is structured to support the additions of custom widgets, whereof a short tutorial is shown below. --- ## Install ```bash npm i @openremote/or-dashboard-builder yarn add @openremote/or-dashboard-builder ``` ## Terminology: To be clear about what all functionalities are meant for, we created a list of terms used within `or-dashboard-builder`. Here it is: | Term | Definition | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Dashboard** | The board / area that contains widgets. (stored in database) | | **Widget** | The object on the dashboard that contains information like content (stored in database) | | _WidgetContainer_ | Wrapper that displays widget content, header, and its actions | | _WidgetSettings_ | The available settings to customise WidgetConfig, | | **Insights** | 'The showcase term' we use for the page in our Manager App. We also have an "Insights app" that is a standalone app for viewing your dashboards. |
Here is an overview of all elements used: | HTML Tag | Description | | --------------------------- | -------------------------------------------------------------------------------- | | or-dashboard-builder | Contains the layout of the full dashboard builder. Keeps track of state as well. | | or-dashboard-preview | Manages grid, and the widgets loaded onto it. | | or-dashboard-browser | Lists widget(s) in cards that can be dragged onto `or-dashboard-preview` | | or-dashboard-tree | Lists dashboards | | or-dashboard-boardsettings | Managing dashboard settings | | or-dashboard-widgetsettings | Wrapper that displays settings of the selected widget (`or-widget-settings`) | | or-widget-container | Manages the loaded widget in that container | | or-widget-settings | Loads and saves widget settings based on the selected widget. | _or-dashboard-engine is a logic class to inject in Gridstack for overriding grid behavior._
_or-dashboard-keyhandler is used to handle keystrokes from the user_

## Creating your own Widget Add your widget manifest to the `registerWidgetTypes()` function in `index.ts`.
This will register the widget, and handle all functions automatically. ```typescript export function registerWidgetTypes() { widgetTypes.set("linechart", ChartWidget.getManifest()); widgetTypes.set("gauge", GaugeWidget.getManifest()); ... // add here } ``` From there, you can add your custom class to the `/widgets` folder and build your HTMLElements.
It is **required** to inherit from `or-widget`, _(or an extended class of it such as or-asset-widget)_
and your custom config should extend on `WidgetConfig`

### Example of a custom Widget Here is a code example of how to create custom widgets.
Feel free to copy, put it in separate files, and adjust it to your needs.
Looking into our existing widgets also helps understanding the codebase. ```typescript import { CustomWidgetConfig } from "./custom-widget"; export interface CustomWidgetConfig extends WidgetConfig { attributeRefs: AttributeRef[]; customFieldOne: string; customFieldTwo: number; } function getDefaultWidgetConfig(): CustomWidgetConfig { return { attributeRefs: [], customFieldOne: "default text", customFieldTwo: 0, }; } @customElement("custom-widget") export class CustomWidget extends OrWidget { // Override of widgetConfig with extended type protected readonly widgetConfig!: CustomWidgetConfig; static getManifest(): WidgetManifest { return { displayName: "Custom widget", // name to display in widget browser displayIcon: "gauge", // icon to display in widget browser. Uses and https://materialdesignicons.com minColumnWidth: 1, minColumnHeight: 1, getContentHtml(config: CustomWidgetConfig): OrWidget { return new CustomWidget(config); }, getSettingsHtml(config: CustomWidgetConfig): WidgetSettings { return new CustomSettings(config); }, getDefaultConfig(): CustomWidgetConfig { return getDefaultWidgetConfig(); }, }; } public refreshContent(force: boolean) { // function that executes on refresh of the widget. // It's normally a 'silent' function that, for example, fetches the data of assets again. } protected render(): TemplateResult { return html` Custom field one: ${this.widgetConfig.customFieldOne} `; } } // Settings element // This can be placed in a seperate file if preferred. @customElement("custom-settings") export class CustomSettings extends WidgetSettings { // Override of widgetConfig with extended type protected readonly widgetConfig!: CustomWidgetConfig; protected render(): TemplateResult { return html` Custom settings `; } protected onButtonClick() { this.widgetConfig.customFieldOne = "custom text"; this.notifyConfigUpdate(); } } ``` --- _Source: https://npm.io/package/@openremote/or-dashboard-builder · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._