Adds a clickable button to your dashboard.
Properties
| Prop | Dynamic | Description |
|---|---|---|
| Group | Defines which group of the UI Dashboard this widget will render in. | |
| Size | Controls the width of the button with respect to the parent group. Maximum value is the width of the group. | |
| Icon | ✓ | Renders a Material Design icon within the button. There is no need to include the "mdi-" prefix. |
| Icon Position | ✓ | If "Icon" is defined, this property controls which side of the "Label" the icon will render on. |
| Label | ✓ | The text shown within the button. If not provided, then the button will only render the icon. |
| Button Color | ✓ | Button Color. If not provided, default theme color will be used. |
| Text Color | ✓ | Text (Label) color. If not provided calculated automatically based on Button color to be Black or White. |
| Icon Color | ✓ | Icon color. If not provided, will have the same color as text / label. |
| Enable pointerup event | Enables the capturing of pointerup events on the button. The output will contain msg._event which details the type of interaction causing the event. | |
| Enable pointerdown event | Enables the capturing of pointerdown events on the button. The output will contain msg._event which details the type of interaction causing the event. | |
| Enable click event | Enables the capturing of click events on the button, i.e.g when both the pointerdown and pointerup events occur whilst the mouse stays inside the button. The output will contain msg._event which details the type of interaction causing the event. | |
| Payload | The msg.payload sent on click. As well as the usual value types, navigate, popup and modal make the button go to a page or open a dialog group. See Navigation and dialogs. | |
| Emulate Button Click | If enabled, any received message will trigger a button click, emitting the relevant payload and topic. |
Dynamic Properties
Dynamic properties are those that can be overriden at runtime by sending a particular msg to the node.
Where appropriate, the underlying values set within Node-RED will be overriden by the values set in the received messages.
| Prop | Payload | Structures | Example Values |
|---|---|---|---|
| Icon | msg.ui_update.icon | String | |
| Icon Position | msg.ui_update.iconPosition | String | |
| Label | msg.ui_update.label | String | |
| Button Color | msg.ui_update.buttonColor | String | |
| Text Color | msg.ui_update.textColor | String | |
| Icon Color | msg.ui_update.iconColor | String | |
| Class | msg.ui_update.class | String |
Controls
| msg. | Example | Description |
|---|---|---|
| enabled | true | false | Allow control over whether or not the button is clickable. |
Navigation and dialogs Added In: v1.36.0
The click payload can make the button act in the dashboard without any extra nodes:
- navigate: go to a page picked from the list, or to Back, Previous page or Next page. Previous and next follow the pages in the navigation menu, skipping hidden pages, disabled pages and links, and wrap around. Back returns to the previous dashboard page, and does nothing if the dashboard was just opened.
- popup: open a dialog group. Clicking outside it or pressing Esc closes it.
- modal: open a dialog group that only closes with its close button.
The lists only show pages and dialog groups of the dashboard the button is in. If a dialog group is on another page, the dashboard switches to that page first and then opens it.
If the page or dialog group a button points at is deleted, the node is marked as invalid in the editor and the list shows it as missing.
The button still sends its message, so a flow can react to the click. msg.payload is set to the page or group name, or to back, prev or next.
"Emulate Button Click" sends the message for a received msg, but doesn't navigate or open the dialog, because the click happens in the browser. Use a ui-control node to navigate or open a dialog from a flow.
Example
Simple Button
Example of a rendered button in a Dashboard.
Measuring Hold Duration
It's possible to configure a button to emit pointerdown and pointerup events. With this, it's possible to measure how long a button is held down for.
The flow to achieve this demo is as follows: