Navigation Menu

Navigation Menu

Navigation Menu is a configurable widget for ThingsBoard dashboards. It helps users build vertical sidebars or horizontal top bars with icon-based menu items, dashboard state navigation, external links, ThingsBoard widget actions, active state highlighting, style presets, and optional custom CSS.

Features

• Vertical sidebar and horizontal top bar layouts
• Compact mode for icon-only navigation
• Material icon support for each menu item
• Dashboard state navigation by State ID
• Optional dashboard state parameters, including dashboard entity and custom parameters
• External URL actions with optional “open in new tab” behavior
• ThingsBoard widget action support
• Active button highlighting based on the current dashboard State ID
• Built-in Dark glass and Light glass style presets
• Custom style mode with background, border, radius, font size, and advanced CSS customization
• No datasource or telemetry configuration required

Data keys

This widget does not require any telemetry, attributes, or data keys.

Navigation Menu is a static dashboard navigation widget. It works through widget settings and the ThingsBoard dashboard state controller.

Basic configuration

Open the widget settings and configure the following sections.

General

Layout

Appearance

Menu item configuration

Each menu item can be configured independently.

Supported action types

Update current dashboard state

Updates the current dashboard state using the configured Dashboard state ID and optional state parameter.

Use this when you want the menu item to navigate inside the same dashboard and optionally pass an entity or custom parameter to the target dashboard state.

Example:

Open dashboard state

Opens the configured dashboard state directly.

Example:

Open external URL

Opens an external link.

Example:

Run ThingsBoard action

Runs a configured ThingsBoard widget action by name.

To use this mode:

1. Add a widget action to the Navigation Menu widget.
2. Use the elementClick action source.
3. Set the menu item Action type to Run ThingsBoard action.
4. Set ThingsBoard action name to the exact action name.

Dashboard state navigation

Navigation Menu highlights the active menu item based only on the current ThingsBoard dashboard State ID.

For example, if your dashboard states are:

Configure menu items like this:

When the current dashboard State ID is state_2, the State-2 menu item is highlighted as active.

Optional state parameters such as dashboard entity or custom parameters are passed to the dashboard state, but they do not control active highlighting.

Optional state parameters

The Add parameter to state setting controls whether Navigation Menu passes an additional parameter to the target dashboard state.

Supported modes:

Use None for regular navigation between dashboard states.

Use Dashboard entity when the target state should display data for a specific Device, Asset, Entity view, or Customer.

Use Custom parameter when your dashboard state, custom widget, or custom action expects a specific parameter name.

Passing an entity to dashboard state

Navigation Menu can pass an entity object through the dashboard state parameter entityId.

Use this configuration:

Example for a device:

This produces a dashboard state parameter similar to:

{
  "entityId": {
    "entityType": "DEVICE",
    "id": "74439270-550c-11f1-aa63-6b62c4bc86ce"
  }
}

Use this together with a dashboard alias configured as “Entity from dashboard state”.

Passing a custom parameter

Navigation Menu can pass a custom dashboard state parameter.

Use this configuration:

Example:

This produces a dashboard state parameter similar to:

{
  "buildingId": "building-A"
}

Custom parameters are useful for custom widgets, dashboard state logic, or actions that read a specific state parameter.

Custom CSS

Custom CSS is available when Style preset is set to Custom.

Use :menu as the root selector. It is automatically scoped to the current widget instance, so the styles do not affect other Navigation Menu widgets on the same dashboard.

Example:

:menu .tb-menu-item:hover {
  background: rgba(0, 188, 212, 0.18);
  color: #00bcd4;
  transform: none;
}

:menu .tb-menu-item.active {
  background: linear-gradient(135deg, #303f9f, #1976d2);
  color: #ffffff;
}

:menu {
  background: rgba(0, 0, 1, 0.75);
  backdrop-filter: blur(14px);
  border: 2px solid rgba(89, 208, 252, 0.9);
}

Value ranges

Navigation Menu does not display telemetry values and does not use color-coded data ranges.

Colors are controlled by the selected style preset, manual appearance settings, or custom CSS.

Recommended widget size

Recommended starting sizes:

The widget can be resized depending on the number of menu items and whether labels are shown.

Typical use cases

• Dashboard side navigation
• Dashboard top navigation
• SCADA page navigation
• Multi-state dashboard navigation
• Device or asset detail page switching
• Compact icon-only navigation panels
• Custom styled dashboard menus