The Histogram Widget Node is a powerful visualization tool that displays values grouped by category. Each category is represented by a vertical or horizontal bar, making it easy to compare performance, distribution and more...
What Is a Histogram?
A histogram organizes data into predefined or dynamically generated categories and presents each group as a bar. The length or height of each bar reflects a calculated metric (e.g., sum, average, last value), allowing users to visually analyze trends, differences, or totals across groups.
Histograms support both Regular (manually defined categories) and Dynamic (data-driven) configurations.
Step-by-Step: How to Configure the Histogram Widget Node
-
Add the widget
-
Drag the Histogram Widget Node from the Visualizations panel to the canvas.
-
-
Connect the widget to the data source
-
Connect the widget to the upstream node that emits the category and value fields.
-
In Regular mode, connect JSON fields that map directly to category names and values.
-
In Dynamic mode, connect a payload that contains nested objects representing categories and series.
-
-
Open configuration
-
Double-click the widget to open the settings window.
-
General Settings
| Field | Requirement | Description |
|---|---|---|
| Widget Name* | Required | Title of the widget (e.g., Energy by Zone). |
| Widget Subtitle | Optional | Additional context below the main title. |
| Show UID / Label Name | Optional | Toggle to display device UID or label. |
| Dynamic Categories* | Required | Choose Regular for manual setup or Dynamic for auto-generation. |
| Data Display* | Required | Select Cluster or Stacked. |
| Direction Display* | Required | Choose Vertical or Horizontal. |
| Calculation Interval* | Required | Time interval for metric calculation. |
| Unit of Measurement* | Required | Unit for time interval (e.g., Seconds, Minutes). |
| Refresh Interval (seconds) | Required | How often the chart refreshes (default: 60s). |
| X-axis Title | Optional | Label for the horizontal axis. |
| Y-axis Title | Optional | Label for the vertical axis. |
| Y-axis Minimum / Maximum | Optional | Set range bounds for the Y-axis. |
| Number of Categories to Display | Optional | Limit how many categories are shown at once. |
| JSON Key for Target Line | Optional | Overlay a reference line across the chart using this value. |
| Display Tooltip Total | Optional | Toggle to show sum in tooltips. |
| Display Column Total | Optional | Toggle to show bar total at the top. |
Regular Histogram Setup
Use this mode to manually define fixed categories.
| Field | Requirement | Description |
|---|---|---|
| Category JSON Key* | Required | JSON key for value calculation per category. |
| Category Name* | Required | Display name for the category. |
| Calculation* | Required | Last, Sum, Average, Min, Max. |
| Decimal Places | Optional | Number of decimal places to display. |
| Hex Color | Optional | Set a custom bar color. |
➕ Use the Add Category button to define more bars.
Dynamic Histogram Setup
Use this mode when categories and series are dynamically generated from incoming JSON.
Expected format:
{
"data_field_name": {
"Category 1": [{"Legend 1": "10"}, {"Legend 2": "20"}],
"Category 2": [{"Legend 1": "12"}, {"Legend 2": "25"}]
}
}
| Field | Requirement | Description |
|---|---|---|
| Data Field Name* | Required | Top-level key containing nested categories. |
| Default Function* | Required | Aggregation method: Last, Sum, Average, etc. |
| Units of Measurement* | Required | Unit of time for aggregation. |
| Columns Order Type* | Required | Sort bars by name or value. |
| Columns Order* | Required | Choose Ascending or Descending. |
| Decimal Precision | Optional | Set rounding precision. |
| Show Total* | Required | Toggle to display grouped totals on bars. |
Series Settings (Dynamic Only)
| Field | Requirement | Description |
|---|---|---|
| Add Series | Optional | Add one or more sub-bars (series) inside each category. |
| Series Type | Optional | Value from workflow or Reference. |
| Value | Required if workflow | JSON key such as Legend 1. |
| Function | Optional | Last, Sum, Average, etc. per series. |
| Series Name | Optional | Used for Reference series. |
| Formula | Optional | Create calculated bars using expressions. |
| Straight Line Function | Optional | Draw a line using aggregated series values. |
| Hex Color | Optional | Custom color for series bars. |
Tooltip & Interface
| Field | Requirement | Description |
|---|---|---|
| Enable Tooltip | Optional | Toggle tooltip visibility. |
| Tooltip Text | Optional | Custom message shown in tooltip. |
| Add to Interface* | Required | Assign this widget to dashboard interfaces. |
Grouping Options
| Field | Requirement | Description |
|---|---|---|
| Select Label | Required if grouped | Filter or group by device label. |
| Grouped Display Mode* | Required | - No Grouping - Group by Label Value - Group by Label Name |
| Number of Widgets to Display | Optional | Limit how many grouped widgets appear. |
Use Cases
-
Compare production totals across machine types
-
Show energy consumption by department
-
Visualize counts of error states
-
Plot real-time sensor data distribution across zones
Best Practices
-
Use Regular mode for consistent categories and color control.
-
Use Dynamic mode when data is variable or JSON is nested.
-
Enable column totals for quick insight at a glance.
-
Use series settings for multi-legend or reference overlays.
-
Keep refresh intervals appropriate to your data update rate.
Frequently Asked Questions (FAQ)
Q: Can I show both actual and calculated values?
A: Yes. Use Series Settings with formulas to overlay references.
Q: What's the difference between clustered and stacked?
A: Clustered shows separate bars side-by-side. Stacked builds values atop each other.
Q: Can I limit how many categories are shown?
A: Yes. Use Number of Categories to Display to set a maximum.
Q: How do I handle missing data?
A: Missing values are ignored or shown as zero based on your aggregation function.