Action Button

• Trigger navigation between dashboard states or open a different dashboard on click.
• Open external URLs or run custom JavaScript for any behavior not covered by built-in actions.
• Highlight the button automatically when a condition is met, like marking the active tab in a navigation bar.
• Disable the button automatically when an action is unsafe or unavailable, like blocking a “Start” button while an alarm is active.
• Trigger native mobile device features like the camera, QR scanner, or GPS.

1. Open the dashboard in edit mode. Click Add widget in the top toolbar, or click the Add new widget icon in the center of an empty dashboard.
2. In the widget bundle selection dialog, find and click Buttons.
3. Select the Action button widget.
4. Configure the datasource, behavior, and appearance, then click Add.

All settings in this section use Basic mode — a quick-start configuration covering the essentials. For finer widget controls like card style, card buttons, title, and tooltip, switch to the Advanced tab.

Select the datasource for the widget:

• Device — a specific device; the button reads attribute and telemetry data from this device to drive the Activated and Disabled states.
• Entity alias — a set of entities matched by an entity alias; use this when the target device is selected dynamically at runtime.

The Behavior section defines what the button does when clicked, when it highlights as active, and when it disables. Configure each sub-section as needed. A simple navigation button requires only On click; Activated state and Disabled state are optional.

Defines what happens when the user presses the button. Select one action type from the list below.

• Do nothing

  Button is clickable but performs no action. Use while testing styles or as a placeholder.

• Navigate to new dashboard state

  Switches to a different view within the same dashboard, like opening a device details screen.

  Parameter	Description
  Target dashboard state	The state to open (required).
  Set entity from widget	Passes the current entity to the target state.
  State entity parameter name	The key the entity is passed under.
  Dashboard state display option	Normal (same view), In separate dialog (popup), or In popover (inline overlay).
  Open right dashboard layout	Opens a side panel instead of replacing the view (mobile only).

• Update current dashboard state

  Updates the context of the current view, like switching the selected device, without navigating away.

  Parameter	Description
  Target dashboard state	The state to switch to (optional).
  Set entity from widget	Passes the current entity to the updated state.
  State entity parameter name	The key the entity is passed under.
  Open right dashboard layout	Opens a side panel on mobile.

• Navigate to other dashboard

  Opens a completely different dashboard, like jumping from a device overview to a global alarms view.

  Parameter	Description
  Target dashboard	The dashboard to open (required).
  Target dashboard state	The specific view to open within that dashboard.
  Open in a new browser tab	Opens the dashboard without leaving the current page.
  Set entity from widget	Passes the current entity to the other dashboard.
  State entity parameter name	The key the entity is passed under.

• Custom action

  Runs custom JavaScript on click to implement any behavior not covered by the built-in options. Use it to make HTTP requests, open custom dialogs, call other widget APIs, or interact with external services. The function receives: $event, widgetContext, entityId, entityName, additionalParams, entityLabel.

• Custom action (with HTML template)

  Same as Custom action, but also renders a custom HTML panel or dialog when the button is clicked.

  Parameter	Description
  Resources	External scripts and styles.
  CSS	Styling.
  HTML	Layout.
  JS	Logic.

• Mobile action

  Triggers a native device feature inside a ThingsBoard mobile app, like the camera or QR scanner.

  Parameter	Description
  Mobile action type	Take picture from gallery, Take photo, Open map directions, Open map location, Scan QR Code, Make phone call, Get phone location, Take screenshot, or Device provision.

• Open URL

  Opens a website or external link when clicked.

  Parameter	Description
  URL	The address to open (required).
  Open in a new browser tab	Keeps the current dashboard open while opening the link.

The Activated state visually highlights the button when a configured condition is met. Use this for active navigation tabs, device mode indicators, or context-driven UI states.

• Do nothing

  Set the activated state manually. No live data needed.

  Parameter	Description
  Value	Set to True to keep the button always highlighted, or False to always show it as inactive.

• Get attribute

  Highlight the button based on a device or entity attribute, like a mode flag or status field.

  Parameter	Description
  Attribute scope	Where the attribute is stored: Any, Client, Server, or Shared.
  Attribute key	The attribute name to read, like mode or online.
  Condition (None)	Highlighted when the attribute equals the value you specify (String, Integer, Double, Boolean, or JSON).
  Condition (Function)	Highlighted when your f(data) function returns true.

• Get time series

  Highlight the button based on the latest telemetry reading from the device.

  Parameter	Description
  Time series key	The telemetry key to monitor, like status or mode.
  Condition (None)	Highlighted when the telemetry value equals the value you specify.
  Condition (Function)	Highlighted when your f(data) function returns true.

• Get alarm status

  Highlight the button when a specific alarm is currently active on the entity.

  Parameter	Description
  Alarm severity	Which severity levels trigger the highlight: Critical, Major, Minor, Warning, or Indeterminate.
  Alarm types	Any alarm, or a specific alarm type.

• Get dashboard state id

  Highlight the button based on which dashboard state is currently open; use this to mark the active tab in a custom navigation bar.

  Parameter	Description
  Condition (None)	Highlighted when the current state name matches the text you enter.
  Condition (Function)	Highlighted when your f(data) function returns true.

• Get dashboard state object

  Highlight the button using the full dashboard state context; use this when you need to check multiple state parameters at once.

  Parameter	Description
  Condition (Function only)	Write a f(data) function that returns true to highlight the button.

The Disabled state makes the button non-interactive when a configured condition is met, preventing clicks in unsafe or invalid situations.

• Do nothing

  Set the disabled state manually. No live data needed.

  Parameter	Description
  Value	Set to True to always disable the button, or False to always keep it enabled.

• Get attribute

  Disable the button based on a device attribute, like an online status or a locked flag.

  Parameter	Description
  Attribute scope	Where the attribute is stored: Any, Client, Server, or Shared.
  Attribute key	The attribute name to read, like online or locked.
  Condition (None)	Disabled when the attribute equals the value you specify (String, Integer, Double, Boolean, or JSON).
  Condition (Function)	Disabled when your f(data) function returns true.

• Get time series

  Disable the button based on the latest telemetry value, like an operational mode or sensor reading.

  Parameter	Description
  Time series key	The telemetry key to monitor, like mode or state.
  Condition (None)	Disabled when the telemetry value equals the value you specify.
  Condition (Function)	Disabled when your f(data) function returns true.

• Get alarm status

  Disable the button while a specific alarm is active, like blocking a “Start process” action while a Critical alarm is open.

  Parameter	Description
  Alarm severity	Critical, Major, Minor, Warning, or Indeterminate.
  Alarm types	Any alarm, or a specific alarm type.

• Get dashboard state id

  Disable the button based on the currently open dashboard state; use this to prevent actions in read-only or restricted views.

  Parameter	Description
  Condition (None)	Disabled when the current state name matches the text you enter.
  Condition (Function)	Disabled when your f(data) function returns true.

• Get dashboard state object

  Disable the button using the full dashboard state context; use this when you need to check multiple state parameters at once.

  Parameter	Description
  Condition (Function only)	Write a f(data) function that returns true to disable the button.

Controls the button’s visual style and label. Changes apply to all states unless overridden by Custom styles.

Setting	Description
Layout	Button visual style: Outlined (bordered), Filled (solid fill), Underlined (underline only), or Basic (plain text).
Auto scale	Automatically adjusts font size and element proportions when the widget is resized.
Label	Text displayed on the button. Supports entity variables: ${entityName}, ${entityLabel}.
Icon	Material Design icon displayed next to the label. Configurable size (px).
Color palette	Main: button fill color in standby; Background: surrounding area color.
Custom styles	Per-state style overrides: Enabled, Hovered, Pressed, Activated, Disabled. Each state supports Main, Background, and Shadow settings.

Setting	Description
Card border radius	Roundness of card corners.

The Action button widget supports the Widget header button action — adds a button to the widget header that triggers a configured action when clicked.

Button Does Not Reflect the Expected State

Cause	Solution
Incorrect attribute key	Verify the key matches the device attribute exactly. Key names are case-sensitive.
Wrong attribute scope	Match the scope to the actual attribute type (Client / Server / Shared).
No attribute on device	Open Devices → Attributes and confirm the key exists with a value.
Result converter always returns the same value	Review the Function converter; check for a missing return statement or incorrect comparison.

Button Click Has No Effect

Cause	Solution
Action type misconfigured	Confirm the configured action type matches the intended behavior (navigation, URL, JavaScript).
Target dashboard state does not exist	For navigation actions, verify the target state name exists in the dashboard.
Mobile action not supported in browser	Mobile actions only work inside a ThingsBoard-based mobile application.
URL missing protocol	Ensure the URL starts with https:// or http://.
Custom action JavaScript error	Open the browser console to see the error. Check for missing return statements, undefined variables, or incorrect widgetContext API calls.