# State graph

**Category:** Control

**Version:** 1.0

**Last Updated:** February 24, 2026

**Author:** Any2Info

***

### Description

The **Stategraph control** visualizes state-based timelines on a dashboard using a linked **Dataclip** as its data source.

The control renders horizontally stacked state segments across a time-based X-axis. Each segment represents a specific state during a defined time span. The Y-axis represents distinct items (YItems), where each item contains a sequence of non-overlapping state segments.

This control is designed for visualizing lifecycle transitions, operational states, and time-bound progressions.

***

### Data Model

Each row in the linked Dataclip represents a single state interval.

Expected structure example:

| YItems | StateStart | StateEnd | StateLabel | StateColor |
| ------ | ---------- | -------- | ---------- | ---------- |

Multiple rows per YItem are expected. Each YItem results in a distinct horizontal line composed of sequential state segments.

Segments must not overlap for the same YItem. Each timespan represents exactly one state.

***

### Required Mappings

All mappings listed below are mandatory.

| Mapping    | Required | Description                                                                                                           |
| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| YItems     | Yes      | Determines the items displayed on the Y-axis. Each distinct value results in a separate horizontal line in the graph. |
| StateStart | Yes      | Defines the start datetime of the state segment.                                                                      |
| StateEnd   | Yes      | Defines the end datetime of the state segment. Together with StateStart, determines the duration of the segment.      |
| StateLabel | Yes      | Defines the textual value representing the state shown within the segment.                                            |
| StateColor | Yes      | Defines the visual color of the state segment.                                                                        |

Correct behavior depends heavily on proper field typing and clean time interval logic in the Dataclip.

***

### Rendering Behavior

* The X-axis represents time.
* The Y-axis represents distinct YItems.
* Each YItem renders as a sequence of horizontally stacked segments.
* Segments are generated based on distinct YItem values encountered in the dataset.
* Segments for the same YItem must not overlap.
* Each segment represents exactly one state during a specific time span.

If overlapping segments exist for the same YItem, rendering behavior is undefined and may result in visual inconsistencies.

***

### Interaction

#### Hover Tooltip

Each segment provides a hover tooltip.

The tooltip displays contextual information derived from the mapped fields, typically including:

* YItem
* StateLabel
* StateStart
* StateEnd

This enables precise inspection of state durations without cluttering the visual layout.

#### Zooming

Basic graph zoom functionality is supported.

Users can zoom into a specific time range on the X-axis to inspect shorter intervals in greater detail. Zooming affects only the visible time window and does not modify the underlying dataset.

***

### Supported Events

#### onUpdate

**Trigger condition:**\
The `onUpdate` event is triggered when the graph updates its data.

This occurs when:

* The control performs its initial data load.
* A linked value changes, causing the Dataclip to refresh.
* The underlying dataset is re-evaluated.

This event can be used to:

* Trigger dependent dashboard logic
* Synchronize other controls
* Execute follow-up actions after data refresh

***

### Usage

Use the **Stategraph control** when visualizing:

* Machine or production states (Running, Idle, Error)
* Order lifecycle progression
* Case or workflow transitions
* SLA tracking
* Resource availability timelines

The control is particularly suited for scenarios where:

* State transitions occur over time
* Duration is a key dimension
* Sequential state progression must be visually clear

***

### Data Requirements & Constraints

* `StateStart` and `StateEnd` must be valid datetime values.
* `StateStart` must be earlier than `StateEnd`.
* Segments for the same YItem must not overlap.
* All required mappings must be configured.
* Missing mappings prevent correct rendering.

Data preparation and validation at the Dataclip level are essential.

***

### Tips & Best Practices

* Pre-sort data by YItems and StateStart for consistent rendering.
* Validate that no overlapping intervals exist per YItem before binding.
* Use consistent StateColor values for identical states across YItems.
* Limit the number of YItems to maintain dashboard readability.
* Use zoom functionality for detailed time analysis.
* Leverage `onUpdate` when synchronization with other dashboard components is required.

***

### Errors & Troubleshooting

| Issue                            | Possible Cause                                        | Solution                                             |
| -------------------------------- | ----------------------------------------------------- | ---------------------------------------------------- |
| Segments overlap visually        | Overlapping StateStart/StateEnd values for same YItem | Validate dataset to ensure non-overlapping intervals |
| Graph not rendering              | Missing required mapping                              | Verify all five required mappings are configured     |
| Incorrect durations              | Invalid datetime format                               | Validate Dataclip field types                        |
| Graph not refreshing as expected | Linked value not triggering update                    | Verify data binding and event configuration          |

***

### Changelog

| Version | Date              | Change                               |
| ------- | ----------------- | ------------------------------------ |
| 1.0     | February 24, 2026 | Initial documentation version added. |