Node-RED UI Level Indicator

0.1.46 · active · verified Wed Apr 22

node-red-contrib-ui-level is a custom Node-RED node designed to provide a linear level indicator widget for the Node-RED Dashboard. It enables users to visually represent numerical data as a customizable bar graph. The current stable version provided is 0.1.46. This node is part of the Node-RED ecosystem, typically seeing updates driven by Node-RED and Node-RED Dashboard releases, and new feature additions. Key differentiators include its support for three layouts (Single Horizontal, Pair Horizontal, Single Vertical), extensive color customization options (multiple segments, single color, interpolated), an optional 'Peak mode' with adjustable hold times, and dynamic configuration of properties like min/max values, segments, and labels via `msg.control` inputs. It also offers multiple stripe resolutions and animation options, providing flexibility for various dashboard designs.

Common errors

```
Error: "ui-level" not found in palette.
```
cause The node-red-contrib-ui-level package is not installed or Node-RED has not been restarted after installation.

fix Install the package via 'Manage palette' in the Node-RED editor or run `npm install node-red-contrib-ui-level` in your Node-RED user directory and restart Node-RED.
```
The level indicator does not update or shows incorrect values.
```
cause The incoming `msg.payload` is not a valid numeric value or cannot be coerced into one, or `min`/`max` values are misconfigured.

fix Ensure `msg.payload` contains a number or a string representing a number (e.g., `msg.payload = 15` or `msg.payload = "15"`). Check the node's configuration for correct `min` and `max` settings.
```
Dashboard widget appears distorted or text is cut off.
```
cause The widget's configured size (e.g., 1x1) is too small for the selected display options (e.g., showing tick values and the main value simultaneously), or font sizes are too large.

fix Increase the widget's size in the Node-RED Dashboard layout, or adjust text size options within the `ui-level` node configuration.

Warnings

gotcha Enabling text animation for the value display can significantly impact dashboard performance, especially on less powerful devices or with many widgets.
Fix: Disable 'Animation of value text' in the node's configuration if performance issues are observed.
gotcha When using the 'Pair Horizontal' layout, the main 'Label' field of the node is not displayed. Instead, labels for each channel must be configured independently within the node or dynamically via `msg.control`.
Fix: Configure individual channel labels within the node properties for 'Pair Horizontal' layout or use `msg.control = { label: 'New Label for channel X' }` for dynamic updates.
gotcha The widget layout is optimized for Node-RED Dashboard's default `1x1` unit size (48px x 48px). While smaller sizes like 24px x 24px are supported, they may not display intermediate tick values along with the main value field due to space constraints.
Fix: Increase the widget's size in the Node-RED Dashboard layout, or adjust text size options within the `ui-level` node configuration.
gotcha Dynamic updates to the widget's properties (min, max, segments, label, peakreset) require sending an object to the `msg.control` property of the incoming message. Incorrect property names or a malformed `msg.control` object will be ignored.
Fix: Ensure `msg.control` is an object containing valid keys like `min`, `max`, `seg1`, `seg2`, `seg3`, `label`, or `peakreset`, as specified in the documentation.

Install

npm install node-red-contrib-ui-level npm
yarn add node-red-contrib-ui-level yarn
pnpm add node-red-contrib-ui-level pnpm

Imports

UI Level Node

wrong:

import { UILevel } from 'node-red-contrib-ui-level'

correct:

Install 'node-red-contrib-ui-level' via Node-RED's 'Manage palette' feature (Menu -> Manage palette -> Install tab). Alternatively, run 'npm install node-red-contrib-ui-level' in your Node-RED user directory (~/.node-red).

This package provides a custom Node-RED node for the UI Dashboard. It is consumed by the Node-RED runtime and made available in the editor palette, rather than being directly imported into JavaScript code.

Quickstart

This conceptual code demonstrates how `msg.payload` and `msg.control` properties are structured and sent to a Node-RED UI Level node to update its display, dynamically adjust parameters, and control features like peak mode.

// Conceptual JavaScript to simulate messages for the UI Level node
// In Node-RED, you would use an Inject node connected to a UI Level node.

function simulateFlow() {
  // Scenario 1: Basic value update
  let msg1 = { payload: 42 };
  console.log('Sending basic value:', msg1.payload);
  // In Node-RED, this 'msg1' would go to the 'ui-level' node's input.

  // Scenario 2: Change min/max and segment values dynamically
  let msg2 = {
    payload: 75,
    control: { min: 0, max: 100, seg1: 25, seg2: 50, seg3: 75 }
  };
  console.log('Sending value with dynamic control:', msg2.payload, msg2.control);
  // This 'msg2' updates the level, its range, and segment thresholds.

  // Scenario 3: Update label dynamically
  let msg3 = {
    payload: 12.3,
    control: { label: 'Pressure (PSI)' }
  };
  console.log('Sending value with dynamic label:', msg3.payload, msg3.control.label);

  // Scenario 4: Reset peak mode (if enabled)
  let msg4 = {
    payload: 90,
    control: { peakreset: true }
  };
  console.log('Sending value and resetting peak:', msg4.payload);
}

simulateFlow();

view raw JSON →