Dashboards

Dashboards are configurable pages for visualizing and interacting with your IoT data. They are built from widgets — charts, tables, maps, controls, and more — and can display data from any combination of devices, assets, or other entities.

Before diving in, review the key concepts — states, aliases, layouts, actions, and time windows — that make up every dashboard.

---

1. From the sidebar, navigate to the Dashboards.
2. Click the + Add dashboard ⇾ Create new dashboard in the top right corner.
3. Enter a dashboard title (all other settings are optional).
4. If needed: In Owner and groups, change the dashboard owner or add it to a group.
5. Click Add — the dashboard opens automatically.
6. Click Save in the upper-right corner to store it.

---

In the dashboard edit mode, you can add widgets, configure settings, modify the layout, etc.

To switch to dashboard edit mode, click the Edit mode button in the top-right corner.

After making changes, click Save to apply them or Cancel to discard them.

---

The dashboard toolbar provides tools for adding widgets, exporting dashboard, and managing states, layouts, aliases, filters, time window, and other settings.
Some controls are visible only in edit mode; others are available in view mode.

---

The dashboard time window defines the time interval for working with telemetry data. It is used by all time series and alarm widgets unless they are configured to use their own widget time window.

See time window for complete details.

Filters narrow which data appears on the dashboard.

Each filter checks one or more key conditions against an attribute or telemetry key — for example, show only devices where model = "DHT22" and battery < 20.

Multiple key filters are combined with and; within a single key, complex expressions with and/or like (A > 0 and A < 20) or (A = 50 or A = 60) are supported.

Add a filter

1. Enter edit mode and click Filters in the toolbar.
2. Click Add filter.
3. Enter the filter name and click Add key filter.
4. Configure the key filter:
   • Select the key type.
   • Enter the key name.
   • Choose the value type.
   • Define the filter condition: operation and value (static or dynamic).
   • Add additional key filters if needed.
5. Click Add (bottom-right) to save the key filter.
6. Click Add to create the filter.
7. To save and apply the filter click Save.

Aliases define data sources for widgets. Two basic types: Static alias (fixed entity) and Dynamic alias (resolved at runtime based on device type, user context, etc.).

See entity aliases for the full list of alias types and configuration options.

Configure dashboard appearance and behavior — state controller, title, logo, toolbar visibility, layout, and advanced CSS. Click the gear icon in the edit mode toolbar.

State controller

Determines how dashboard states are driven. Default: entity — state is bound to the currently selected entity context.

Title

Enable display dashboard title to show the title in the top-left corner. Adjust color and transparency with the color picker.

Logo

Enable Display logo in dashboard fullscreen mode and upload an image. The logo appears in the top-left corner when the dashboard is in fullscreen.

Toolbar settings

The checkboxes control the visibility of the corresponding options in the dashboard toolbar.

Toggle	Description
Hide toolbar	Entirely hides the toolbar; only the Enter edit mode (pencil) icon is displayed in the top-right corner.
Keep toolbar opened	Keeps the toolbar always expanded; when off, it collapses into a three-dots menu.
Display dashboards selection	Shows/hides the dashboards selector in the toolbar.
Display entities selection	Shows/hides the entities selector in the toolbar.
Display filters	Shows/hides the filters button (only if filters are defined).
Display time window	Shows/hides the time window control.
Display export	Shows/hides the export button.
Display update dashboard image	Shows/hides the update dashboard image button.

Advanced settings

Dashboard CSS — apply custom CSS scoped to the dashboard.

Layout settings

Configure the default layout grid and appearance:

• Columns count — number of columns in the dashboard grid (default: 24).
• Minimum layout width — minimum width in columns before the layout scrolls horizontally.
• Margin between widgets — spacing between widgets in pixels.
• Apply margin to the sides of the layout — adds outer padding around the widget grid.
• Auto fill layout height — stretches the layout to fill the full page height.
• Background color — sets a solid background color for the dashboard.
• Background image — sets a background image (browse from gallery or set a link); configure Background size mode (e.g. Fit width).

Mobile layout settings

• Auto fill layout height — applies auto-fill to the mobile layout.
• Mobile row height — height of each row in the mobile layout (default: 70 px).

Export a visual snapshot of the current dashboard — a pixel-accurate capture of all widgets, charts, and data as displayed on screen at the time of export.

• Formats: PDF, PNG, JPEG
• Best for: sharing reports with stakeholders, printing dashboards, archiving a point-in-time view

This is a visual export — it captures how the dashboard looks, not how it is configured. To export the dashboard configuration for backup or migration, see the Export dashboard section.

Click the Export dashboard button on the right side of the toolbar, then select the desired format: PDF, PNG, or JPEG.
The snapshot is generated and automatically downloaded to your device.

ThingsBoard uses a grid-based layout system to organize widgets within a dashboard.
A single dashboard can include multiple layouts (states) to support advanced navigation scenarios and different visual configurations for various use cases and screen sizes.

See Layouts for full details.

States create a layered hierarchy in your dashboard — for example, a root state listing all devices and a detail state showing data for a selected device.

To access states management, in edit mode, click the States icon (Manage dashboard states) on the left of the toolbar.

Add a state

1. In edit mode, click Manage dashboard states in the toolbar.
2. Click the + icon in the top-right of the Manage dashboard states dialog.
3. Enter a state name (the State ID is auto-generated but editable). Use ${entityName} for dynamic naming.
4. Click Add, then Save.

Root state

Every dashboard starts with a single Root state. To change which state is the root, edit the state and enable the Root state checkbox.

Configuring the appropriate widget action allows you to navigate between dashboard states.

In this example, the Navigate to new dashboard state action type is used.

Preparation

Add a new dashboard state. Use ${entityName} as the state name for dynamic naming.

Configure widget action

1. Open the dashboard in Edit mode.
2. Click the edit (pencil) icon on the widget to open its settings.
3. Navigate to the Actions tab.
4. Click + Add action.
5. Configure the action parameters:
   • Action source: e.g., Widget header button or On row click
   • Name: enter a descriptive name
   • Action type: Navigate to new dashboard state
   • Target state: select the previously created state
   • Click Add.
6. Click Apply to save widget changes.
7. Click Save to save the dashboard.

Test navigation

After saving the dashboard, trigger the configured action (e.g., click the widget header button).

The dashboard switches to the target state.

Widgets are the core building blocks of a dashboard — including charts, tables, maps, controls, alarms, and other visualization components.
Widgets provide configurable settings and parameters that allow users to customize behavior and appearance according to specific use cases.

For detailed information, see Widgets.

Reassign the dashboard to a different owner or move it into a group. Only users associated with the selected owner will have access.

1. Go to the Dashboards page.
2. Click the Manage owner and groups icon next to the dashboard.
3. In the Owner field, select a new owner from the dropdown.
4. Optionally, select an existing dashboard group or create a new one.
5. Click Update.

In ThingsBoard PE, dashboards cannot be shared individually. A dashboard must be shared as part of a dashboard group that contains the required dashboard.

When sharing, choose a permission level:

• Read — the customer can view the dashboards but cannot modify them.
• Write — the customer can view and edit the dashboards.
• Role — apply a previously created custom Role with fine-grained permissions.

1. Go to the Dashboards ⇾ Groups.
2. Click the Share icon next to the dashboard group.
3. Select the customer(s) to share with.
4. Set the permission: Read, Write, or select a previously created Role.
5. Click Share.

Make a dashboard group and all its dashboards public to allow access without authentication.
This is useful for providing read-only access to external users without a ThingsBoard account, displaying dashboards on public screens, or embedding them into external websites.

1. Go to the Dashboards ⇾ Groups.
2. Click the Make public icon next to the dashboard group.
3. Confirm making the group public.

Share a link to a public dashboard.

1. Open the now-public group and click the Public dashboard link icon next to the desired dashboard.
2. Click Copy public link and share it.

To revert, click the Make private icon next to the dashboard group and confirm.

Edit the dashboard title and description through the dashboard details panel.

1. Go to the Dashboards.
2. Click the Dashboard details icon next to the dashboard.
3. In the dashboard details window, click the pencil icon to enter edit mode.
4. Make the necessary changes.
5. Click Apply changes to save.

Export a dashboard’s configuration as a JSON file. This captures the dashboard structure, widget settings, and layout — not a visual snapshot of the data.

Use this for:

• Backup — save a copy of a dashboard configuration
• Migration — move dashboards between ThingsBoard instances or environments
• Reuse — copy an existing dashboard as a starting point for a new one
• Version control — store dashboard configurations alongside your project code

Two ways to export:

• On the Dashboards page, click the Export dashboard icon next to a dashboard.
• Inside a dashboard, click the Export dashboard button in the toolbar and select Export JSON configuration.

To export the dashboard as a visual image or PDF instead, see Export as PDF, PNG, or JPEG.

Import the dashboard by uploading its configuration from a JSON file.

1. Go to the Dashboards.
2. Click + Add dashboard ⇾ Import dashboard.
3. Upload the .json file with the dashboard configuration and click Import.

Click the trash icon next to the dashboard and confirm deleting, or open the dashboard details page and click Delete dashboard.

---

Capability	Description	Guide
Visualize IoT data	Add widgets to display telemetry, attributes, and alarms from any device or asset in real time or historically	Widgets
Configure the time window	Set the time interval and aggregation rules applied to all time-series widgets on the dashboard	Time window
Use entity aliases	Make widgets context-aware by resolving entities dynamically — by type, group, relation, or dashboard state	Entity aliases
Build multi-state navigation	Create separate dashboard states for detail views, drill-downs, or device-specific pages and navigate between them with widget actions	Widget actions
Configure widget actions	Trigger navigation, RPC commands, or attribute updates when users click on charts, table rows, or buttons	Widget actions
Control the dashboard layout	Arrange widgets on a responsive grid, configure mobile layout, and create multiple named layouts for different screen contexts	Layouts
Share with customers	Assign dashboards to customer accounts so their users see only their own data without access to tenant-level configuration	Customers
Set as home dashboard	Assign a dashboard as the default landing page for a tenant, customer, or individual user after login	Home dashboard
Export and import	Export a dashboard as a JSON file and import it into another ThingsBoard instance for backup or reuse	Import and export
Version control	Track dashboard configuration changes, compare versions, and restore previous states using the version control service	Version control