Button Switch

The ui-btn-switch node shows a configurable toggle button for Node-RED Dashboard 2. It lets you switch between two states (false and true) with customisable labels, and offers two visual styles: Action (standard blue style) and Session (red for the false/off state and green for the true/on state).

Besides syncing its state from the flow messages, the widget supports advanced options such as requiring a session configuration before activating a Session switch, asking for a password before changing state, and enabling or disabling the control through msg.enabled.

Features

• Visible, editable button label.
• Editable labels for the false and true states.
• Action and Session visual styles.
• Optional inversion of the session colours (false/off in green and true/on in red).
• Optional required session configuration before activating a Session switch.
• Optional password before toggling the state.
• State syncing from the flow messages.
• Support for enabling and disabling the control through msg.enabled.

Configuration

Property	Description	Default
group	Dashboard group the widget belongs to (required).	—
name	Node name in the editor.	''
order	Order within the group.	0
width	Widget width.	0
height	Widget height.	0
buttonName	Button label shown before the switch, for example Ejector or Session.	'Expulsor'
falseLabel	Text for the inactive state, for example Inactive or Off.	'Inactivo'
trueLabel	Text for the active state, for example Active or On.	'Activo'
switchType	Switch type: action uses the standard blue style; session uses red for false/off and green for true/on.	'action'
invertSessionColors	For Session switches, inverts the state colours (false/off in green and true/on in red).	false
requireSessionConfig	For Session switches, requires a configuration field before activating.	false
sessionConfigSource	Source of the required configuration: msg (last received message) or global (Node-RED global context).	'global'
sessionConfigField	Dotted path where the session configuration is expected, for example payload.sessionConfig, sessionConfig or global.sessionConfig.	''
askPassword	Asks for a password before changing state.	false
password	Password required to toggle the state.	''
passwordLabel	Label of the password field.	'Password'
cancelText	Text of the cancel button.	'CANCEL'
confirmText	Text of the confirm button.	'CONFIRM'

Input

The node has 1 input (inputs: 1). It processes the following msg properties to set the switch state or to enable/disable it.

msg.payload (boolean): sets the state directly.

msg.payload = true;

msg.payload.status (boolean): sets the state through an object property, which allows it to be accompanied by the session configuration.

msg.payload = {
  status: false,
  sessionConfig: {
    user: "operator"
  }
};

msg.enabled (boolean): enables or disables the switch.

msg.enabled = false;

When the switch is of type session, requires configuration (requireSessionConfig) with source global, and an activation is attempted, the node validates that the configuration exists at the path given by sessionConfigField within the global context. If it is not found, the widget rejects the activation and shows an error such as Missing session config: global.<field>.

Output

The node has 1 output (outputs: 1). When the switch changes state, it emits:

msg.payload = true;

The value is true for the true state and false for the false state.

The output also includes:

msg.topic = "Expulsor";
msg.state = {
  value: true,
  label: "Activo",
  name: "Expulsor"
};

When the session configuration is validated from the global context, the msg.state object also includes a sessionConfig property with the retrieved configuration.

Usage example

Configuration of a simple action switch (Bypass):

Button label: Bypass
False label: Off
True label: On
Switch type: Action

To set the switch state from the flow, send it a message from a function node with the desired state in msg.payload:

msg.payload = true;
return msg;

Example of a session switch that requires a global configuration before activating:

Button label: Session
False label: Off
True label: On
Switch type: Session
Require config: enabled
Config source: Global context
Config field: sessionConfig

With this configuration, the user can only activate the switch if a value exists in global.sessionConfig; otherwise the widget shows an error message and keeps the state at false.