Node-RED Dashboard 2.0: Install Buttons, Switches and Gauges
Node-RED connects systems, but many projects also need an interface: a button to request an action, a switch for an output and a gauge for the latest sensor value. FlowFuse Dashboard, also called Node-RED Dashboard 2.0, adds UI nodes for building that interface from a flow.
This guide uses the current package @flowfuse/node-red-dashboard. Do not confuse it with the older node-red-dashboard package, which is deprecated. The names are similar; the node types, configuration model and migration experience are not identical.
You will install the package, create a dashboard page, connect widgets to messages, test a simple interface and learn how to avoid common issues. Start with a test flow before connecting a relay or other physical load.
Before you install
You need a working Node-RED runtime and access to its editor. If you are starting on Raspberry Pi 5, follow Install Node-RED on Raspberry Pi 5. The browser opens the editor; the dashboard is a separate web UI served by the same runtime.
Keep a backup of your flows before changing palette packages. If an older dashboard is already installed, do not uninstall it casually from a production flow. The two dashboard packages can coexist while you build and test the new interface.
1. Install FlowFuse Dashboard
In the Node-RED editor:
- Open the menu and choose Manage Palette.
- Select the Install tab.
- Search for @flowfuse/node-red-dashboard.
- Verify the complete package name and install it.
- Wait until installation completes, then look for the new UI nodes.
Use the current FlowFuse Dashboard getting-started guide if editor labels have changed. Do not install the legacy node-red-dashboard package for a new implementation.
2. Create the first dashboard page
Drag a Dashboard 2.0 UI node such as ui-button onto the workspace. Open its configuration and select or create the dashboard, page and group it should belong to. Dashboard 2.0 organises the UI into a hierarchy: a dashboard has pages, pages contain groups, and groups contain widgets.
The first UI widget can create the initial dashboard structure for you. Deploy the flow, open the dashboard URL shown by the node/package configuration (the default base path is commonly /dashboard), and check that it loads from the same Node-RED host and port. If you changed the base path, use your configured path rather than assuming the default.
3. Connect a button to a flow
Connect the button output to a Debug node, deploy, open the dashboard in another browser tab and click the button. Inspect the message in Debug before connecting it to a device.
A widget's exact message shape depends on its configuration and node type. Never assume its payload is a string or number without inspecting it. Once verified, route it to a Change or Function node and normalize it into an explicit command schema.
For an ESP32 project, a button can publish a command through MQTT, but validate the allowed values in firmware and receive reported state separately. A browser interaction proves only that the UI emitted a message—not that hardware completed the action.
4. Add a switch for a two-state control
Add a ui-switch widget and configure its label, group and on/off values. Connect it to Debug and verify which payload is emitted for each position. Make the value convention explicit—0/1, false/true or a string command—and normalize it before passing the message to a device.
For physical hardware, distinguish requested state from reported state. A webpage switch can change while the device is offline. If the interface displays that click as though it proves the GPIO changed, it can mislead the operator. Build feedback from the device or broker and display connection/staleness separately.
Do not use a web dashboard as the only safety control for mains voltage, motors or other hazardous loads.
5. Add a gauge for sensor data
Add a ui-gauge widget, choose a clear label and configure range and unit. Feed it a known numeric message first, then connect real sensor telemetry. If a sensor publishes JSON containing temperature and pressure, select the intended property before the gauge rather than passing the whole object.
Validate the type. For a temperature gauge, reject a missing or non-numeric value and choose a range based on the actual sensor. A displayed zero can be a valid measurement or a conversion bug; keep freshness and availability visible so users can tell the difference.
A practical next project is Control an ESP32 LED with Node-RED and MQTT, then progress to a live DHT11/BMP280 dashboard once the sensor integration is ready.
Troubleshooting
The UI nodes do not appear: Confirm the exact package installed and wait for palette installation to finish. Refresh the editor if necessary and inspect Node-RED logs.
The dashboard URL returns 404: Check the dashboard base path and configured port, verify the runtime is running, and ensure a UI node has been configured and deployed.
The widget appears but does nothing: Wire it to Debug, deploy, and inspect the full message. Confirm the widget's group/page configuration and that the browser tab shows the correct Node-RED instance.
The gauge shows zero or blank: Verify the incoming payload type and property path. Convert and validate the value deliberately.
Existing Dashboard 1 widgets do not transfer: Dashboard 2.0 is a different package and migration may require rebuilding widgets and checking behavior. See the official migration guide.
Migrating from the legacy dashboard
The legacy node-red-dashboard package is deprecated. For new work, install @flowfuse/node-red-dashboard. Existing flows may use legacy widget nodes and layout settings, so do not expect package replacement alone to migrate the interface. Back up the existing flows, build the new page in parallel, compare every interaction, test on the target browser and only then retire the older dashboard.
The official FlowFuse migration guide documents current migration options and limitations. Recheck it before a large migration because node coverage and migration support can change.
What to build next
- Node-RED Tutorial for Beginners: Nodes, Flows & msg.payload
- Node-RED with MQTT: Connect Mosquitto, Publish & Subscribe
- Install Node-RED on Raspberry Pi 5
For real-world dashboards, add device availability, last-seen timestamps, safe defaults and authentication. A polished interface is valuable only when its displayed state agrees with what the device has actually reported.