Toggle Button

The Toggle button widget adds a two-state (Checked/Unchecked) control button to any dashboard. Use it to toggle a device between ON/OFF, open/closed, or enabled/disabled states. Each state change can send an RPC command, update a device attribute, or write a time-series record.

• Two-state control (Checked/Unchecked) for any device or entity.
• Reads current device state on load from an attribute, telemetry value, or RPC call.
• Sends RPC commands, attribute updates, or telemetry writes independently for each state change.
• Independent styling for Checked and Unchecked states.
• Can be disabled automatically based on device data, alarms, or dashboard state.

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 Toggle 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 determine its state.
• 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 how the toggle reads its initial state, what fires when it switches to Checked, what fires when it switches to Unchecked, and when it disables. Configure each sub-section as needed; Disabled state is optional.

Determines whether the toggle shows as Checked or Unchecked when the dashboard loads. Select one action type from the list below.

• Do nothing

  The state is set manually. No live data needed.

  Parameter	Description
  Value	Set to Checked to always show the button as on, or Unchecked to always show it as off.

• Execute RPC

  Calls a device RPC method to read the current state.

  Parameter	Description
  Method	The RPC method name to call, like getState.
  Condition (None)	Checked when the RPC result equals the value you specify.
  Condition (Function)	Checked when your f(data) function returns true.

• Get attribute

  Reads a device or entity attribute to determine the current state.

  Parameter	Description
  Attribute scope	Where the attribute is stored: Any, Client, Server, or Shared.
  Attribute key	The attribute name to read, like state or enabled.
  Condition (None)	Checked when the attribute equals the value you specify.
  Condition (Function)	Checked when your f(data) function returns true.

• Get time series

  Reads the latest telemetry value to determine the current state.

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

• Get alarm status

  Sets the toggle to Checked when a matching alarm is currently active on the entity.

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

• Get dashboard state id

  Sets the toggle based on the currently open dashboard state; use this when button state should reflect navigation context.

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

• Get dashboard state object

  Sets the toggle based on 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 set the toggle to Checked.

Defines the action executed when the user toggles the button to Checked, like turning on a device, opening a door, or starting a process. Select one action type from the list below.

• Execute RPC

  Sends an RPC command to the device when checked.

  Parameter	Description
  Method	The RPC method name, like setState.
  Parameters	Constant — a fixed value like true, "ON", or {"state": 1}; Function — a JS function that returns the payload; None — no parameters sent.
  RPC request timeout (ms)	How long to wait for a device response before timing out.
  RPC request persistent	When enabled, the RPC command is stored and retried until the device comes online.

• Set attribute

  Updates a device attribute when checked.

  Parameter	Description
  Attribute scope	Server or Shared.
  Attribute key	The attribute to update, like state or doorState.
  Value	Constant — a fixed value like "opened" or true; Function — a JS function that returns the value.

• Add time series

  Writes a time-series record when checked.

  Parameter	Description
  Time series key	The telemetry key to write to, like state.
  Value	Constant — a fixed value; Function — a JS function that returns the value.

Defines the action executed when the user toggles the button to Unchecked, like turning off a device, closing a door, or stopping a process. Configure this as the reverse of Check. Select one action type from the list below.

• Execute RPC

  Sends an RPC command to the device when unchecked.

  Parameter	Description
  Method	The RPC method name, like setState.
  Parameters	Constant — a fixed value like false, "OFF", or {"state": 0}; Function — a JS function that returns the payload; None — no parameters sent.
  RPC request timeout (ms)	How long to wait for a device response before timing out.
  RPC request persistent	When enabled, the RPC command is stored and retried until the device comes online.

• Set attribute

  Updates a device attribute when unchecked.

  Parameter	Description
  Attribute scope	Server or Shared.
  Attribute key	The attribute to update, like state or doorState.
  Value	Constant — a fixed value like "closed" or false; Function — a JS function that returns the value.

• Add time series

  Writes a time-series record when unchecked.

  Parameter	Description
  Time series key	The telemetry key to write to, like state.
  Value	Constant — a fixed value; Function — a JS function that returns the value.

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.

• Execute RPC

  Disable the button based on a device RPC response, like checking availability before allowing control.

  Parameter	Description
  Method	The RPC method to call, like getAvailability.
  Condition (None)	Disabled when the RPC result equals the value you specify.
  Condition (Function)	Disabled when your f(data) function returns true.

• 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 availability reading.

  Parameter	Description
  Time series key	The telemetry key to monitor, like availability 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 control 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 widget header and title area.

Setting	Description
Auto scale	Automatically adjusts font size and element proportions when the widget is resized.
Title	Text displayed in the widget header. Supports entity variables: $\{entityName\}, $\{entityLabel\}.
Card icon	Material Design icon shown alongside the title. Configurable size (px).

Controls the button’s visual style independently for each state. The section has two tabs: Checked (ON state) and Unchecked (OFF state).

Setting	Description
Layout	Button visual style: Outlined (bordered), Filled (solid fill), Underlined (underline only), or Basic (plain text).
Label	Text displayed on the button in this state. Supports entity variables: $\{entityName\}, $\{entityLabel\}.
Icon	Material Design icon shown on the button. Configurable size (px).
Border radius	Roundness of button corners (px).
Color palette	Main: button fill or text color; Background: surrounding area color.
Custom styles	Per-interaction style overrides: Enabled, Hovered, Pressed, Activated, Disabled. Each supports Main, Background, and Shadow settings.

Setting	Description
Background	Solid color or image used as the card background.
Show card buttons	Toggle visibility of the Fullscreen button in the card header.
Card border radius	Roundness of card corners.
Card padding	Spacing between card content and its border.

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

Scenario: A smart supermarket has a device called Main Door that controls a door. The device reads its state from the shared attribute doorState and expects attribute updates to open or close the door.

Prerequisites:

• Create a device named Main Door in ThingsBoard.
• Add a shared attribute: Key — doorState, Data type — String, Value — closed.
• Ensure the device subscribes to doorState shared attribute updates.

Step 1. Add the widget. Open your dashboard in edit mode, click Add widget, select the Buttons bundle, then choose Toggle button.

Step 2. Configure the datasource. Set Target device to Main Door.

Step 3. Configure behavior.

Initial state: Get attribute — Scope: Shared, Key: doorState, Condition: None — Checked when result is opened (String).

Check (ON state): Set attribute — Scope: Shared, Key: doorState, Value: Constant — opened (String).

Uncheck (OFF state): Set attribute — Scope: Shared, Key: doorState, Value: Constant — closed (String).

Step 4. Configure button appearance.

Checked tab: Layout — Outlined, Label — Opened, Color palette Main — green.

Unchecked tab: Layout — Filled, Label — Closed, Color palette Main — red.

Step 5. Configure card appearance. Set Card padding to 0px.

Step 6. Save. Click Add, resize and reposition as needed, then click Save on the dashboard toolbar.

Result: The widget reads doorState from Main Door. When doorState = "opened", the button shows Opened (white background, green label); when doorState = "closed", it shows Closed (red fill). Toggling the button writes the new value to doorState — the device receives the update and adjusts its physical state.

Toggle 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.

Toggle does not change state on click

Cause	Solution
Check or Uncheck action misconfigured	Confirm the action type and parameters match your device’s expected interface (RPC method name, attribute key, etc.).
Attribute scope mismatch	For Set attribute actions, the scope must be Server or Shared — Client attributes cannot be written from the dashboard.
Device offline during RPC	If using Execute RPC without persistent mode, the command is dropped when the device is offline. Enable RPC request persistent to queue it.
Wrong value type	Ensure the constant value type (String, Boolean, Integer) matches what the device expects.