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 getting started, review the key concepts — states, aliases, layouts, actions, and time windows — that make up every dashboard.

---

1. From the sidebar, navigate to 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, and more.

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 the 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-level time window sets the time range applied to telemetry data. It applies to all time series and alarm widgets unless they have their own time window configured.

See time window for complete details.

Filters narrow which data appears on the dashboard.

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.

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.

See Filters for more details.

Entity Aliases define data sources for widgets. There are two basic types: a static alias (resolves to a fixed entity) and a dynamic alias (resolved at runtime based on device type, user context, or other criteria).

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

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

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

Each checkbox controls the visibility of a toolbar option.

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 or hides the dashboards selector in the toolbar.
Display entities selection	Shows or hides the entities selector in the toolbar.
Display filters	Shows or hides the filters button (only if filters are defined).
Display time window	Shows or hides the time window control.
Display export	Shows or hides the export button.
Display update dashboard image	Shows or 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.

Dashboard configurations can be exported to a remote Git repository, versioned, and restored at any point in time — enabling backup, rollback to a previous state, and collaborative management of dashboard changes across teams.

See Version Control for full details.

---

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

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 manage states, in edit mode click the States icon (Manage dashboard states) in the toolbar.

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 has one root state. To change it, edit the state and enable the Root state checkbox.

To move between states, attach a Navigate to new dashboard state action to any widget. When the action is triggered — for example, by clicking a row in a table or a button in the widget header — the dashboard switches to the target state.

Before configuring the action, make sure you have already added the target state.

1. Open the dashboard in Edit mode.
2. Click the pencil icon on the widget to open its settings.
3. Go to the Actions tab and click + Add action.
4. Set Action source (e.g., Widget header button or On row click), enter a Name, and set Action type to Navigate to new dashboard state.
5. Select the Target state from the dropdown and click Add.
6. Click Apply, then Save the dashboard.

---

ThingsBoard provides a wide range of customizable widgets — charts, tables, maps, controls, alarms, and more — organized into bundles by category. Each widget offers settings to tailor its appearance and behavior to your use case.

Explore the available widgets and their configuration options in the Widgets documentation.

---

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.

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 Dashboards.
2. Click the Dashboard details icon next to the dashboard.
3. 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 a dashboard from a JSON configuration file.

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

---

Click the trash icon next to the dashboard and confirm the deletion, or open the dashboard details 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	Navigate to new dashboard state
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
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