> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/reference/widgets/display/timeline.md).

# Timeline

State-over-time bars per field across up to six bound data sources, with category colors

<figure><img src="https://3495989837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE5Ketpww1s7TauSAJrJ8%2Fuploads%2Fgit-blob-3fd37c5a0190e8eed605b3cc7b38bda749ba0546%2Fwidget-timeline.png?alt=media" alt="Timeline of filler, capper and labeler states over a shift, with bars for setup, running, fault and idle" width="1048"><figcaption></figcaption></figure>

A timeline shows states over time, one track per machine or signal: when it was running, in setup, in fault or idle. Each state value gets its own color, and the legend explains them. Tracks can come from up to six data sources, so machines recorded apart still share one time axis. Users hover for exact times and can zoom into a stretch of the shift.

**Good for:** machine state histories, downtime analysis, shift and batch sequences.

## Properties

The widget's General tab lists these properties under Receives and Emits. Drop an executor's output, input or trigger onto a row to link it. An example also fills an unlinked widget as demo data in the App Builder.

{% tabs %}
{% tab title="Receives" %}
**`data`** (from an output, `Array<object>`): The data source for timelines. Use an array of objects. Each object must be of identical structure/schema, but may contain multiple properties allowing to plot multiple tracks in one timeline.

<details>

<summary>Example</summary>

```json
[
  {
    "timestamp": "2026-08-12T10:00:00Z",
    "pressure": 2.4,
    "temperature": 61.3
  },
  {
    "timestamp": "2026-08-12T10:05:00Z",
    "pressure": 2.7,
    "temperature": 62.1
  },
  {
    "timestamp": "2026-08-12T10:10:00Z",
    "pressure": 2.5,
    "temperature": 61.8
  }
]
```

</details>

**`data2`** (from an output, `Array<object>`): The data source for timelines. Use an array of objects. Each object must be of identical structure/schema, but may contain multiple properties allowing to plot multiple tracks in one timeline.

<details>

<summary>Example</summary>

```json
[
  {
    "timestamp": "2026-08-12T10:00:00Z",
    "pressure": 2.4,
    "temperature": 61.3
  },
  {
    "timestamp": "2026-08-12T10:05:00Z",
    "pressure": 2.7,
    "temperature": 62.1
  },
  {
    "timestamp": "2026-08-12T10:10:00Z",
    "pressure": 2.5,
    "temperature": 61.8
  }
]
```

</details>

**`data3`** (from an output, `Array<object>`): The data source for timelines. Use an array of objects. Each object must be of identical structure/schema, but may contain multiple properties allowing to plot multiple tracks in one timeline.

<details>

<summary>Example</summary>

```json
[
  {
    "timestamp": "2026-08-12T10:00:00Z",
    "pressure": 2.4,
    "temperature": 61.3
  },
  {
    "timestamp": "2026-08-12T10:05:00Z",
    "pressure": 2.7,
    "temperature": 62.1
  },
  {
    "timestamp": "2026-08-12T10:10:00Z",
    "pressure": 2.5,
    "temperature": 61.8
  }
]
```

</details>

**`data4`** (from an output, `Array<object>`): The data source for timelines. Use an array of objects. Each object must be of identical structure/schema, but may contain multiple properties allowing to plot multiple tracks in one timeline.

<details>

<summary>Example</summary>

```json
[
  {
    "timestamp": "2026-08-12T10:00:00Z",
    "pressure": 2.4,
    "temperature": 61.3
  },
  {
    "timestamp": "2026-08-12T10:05:00Z",
    "pressure": 2.7,
    "temperature": 62.1
  },
  {
    "timestamp": "2026-08-12T10:10:00Z",
    "pressure": 2.5,
    "temperature": 61.8
  }
]
```

</details>

**`data5`** (from an output, `Array<object>`): The data source for timelines. Use an array of objects. Each object must be of identical structure/schema, but may contain multiple properties allowing to plot multiple tracks in one timeline.

<details>

<summary>Example</summary>

```json
[
  {
    "timestamp": "2026-08-12T10:00:00Z",
    "pressure": 2.4,
    "temperature": 61.3
  },
  {
    "timestamp": "2026-08-12T10:05:00Z",
    "pressure": 2.7,
    "temperature": 62.1
  },
  {
    "timestamp": "2026-08-12T10:10:00Z",
    "pressure": 2.5,
    "temperature": 61.8
  }
]
```

</details>

**`data6`** (from an output, `Array<object>`): The data source for timelines. Use an array of objects. Each object must be of identical structure/schema, but may contain multiple properties allowing to plot multiple tracks in one timeline.

<details>

<summary>Example</summary>

```json
[
  {
    "timestamp": "2026-08-12T10:00:00Z",
    "pressure": 2.4,
    "temperature": 61.3
  },
  {
    "timestamp": "2026-08-12T10:05:00Z",
    "pressure": 2.7,
    "temperature": 62.1
  },
  {
    "timestamp": "2026-08-12T10:10:00Z",
    "pressure": 2.5,
    "temperature": 61.8
  }
]
```

</details>
{% endtab %}
{% endtabs %}

## Settings

Double-click the widget in the Page editor to open its settings, grouped in these tabs. Settings marked *set per screen* are pinned by nature: every screen keeps its own value.

<details>

<summary>General</summary>

* **Animate**: Eases the display to new data in one second; off draws every update at once, for fast live data.

</details>

<details>

<summary>Tracks</summary>

* **Time/Date field**: Field holding the timestamp of each record.
* **Timeline tracks**: Rows of the timeline, one per value field, the first on top (on the left when rotated); fields found in the bound data are added at design time.
  * **Track name (y-axis label)**: Label of the row on the track axis; empty shows the value field.
  * **Value field**: Field whose runs of equal values form the colored blocks; each distinct value is a category, and a null or missing value ends the block and leaves a gap.
  * **Show labels**: Prints the category name inside each block of the track.

</details>

<details>

<summary>Colors</summary>

* **Category colors**: Color per category value found in the data, plus a fallback color.
  * **Fallback color**: Color for categories without their own entry; auto or empty takes the theme's accent background.

</details>

<details>

<summary>Legend</summary>

* **Visible**: Shows the legend of categories. *Set per screen.*
* **Title**: Heading above the legend items; empty shows none.
* **Subtitle**: Line under the legend title; shown only with a title.
* **Vertical alignment**: Puts the legend at the top or bottom of the chart. Choices: Top, Bottom. *Set per screen.*
* **Horizontal alignment**: Puts the legend at the left, center or right of the chart. Choices: Right, Center, Left. *Set per screen.*
* **Item text position**: Side of the color marker its text is on; empty picks it from the orientation. Choices: Top, Bottom, Left, Right.
* **Position**: outside keeps the legend beside the plot, inside draws it over the plot area. Choices: Outside, Inside. *Set per screen.*
* **Orientation**: Lays the entries out in a column or a row; empty picks it from the alignment. Choices: Vertical, Horizontal. *Set per screen.*

</details>

<details>

<summary>Look &#x26; feel</summary>

* **Timeline end boundary**: Where each track's last block ends: at the current time (live), or 2 % of the data span past the last data point (snapshot). Choices: Current time (live monitoring), Last point (historical snapshot).
* **Zoom and pan**: disabled: fixed time axis; enabled: wheel zoom and drag pan always on; selectable: a lock button above the timeline turns them on and off. Choices: Disabled, Enabled, Selectable. *Set per screen.*
* **Rotate plot**: Draws the tracks as columns with time running upward; off, tracks are rows with time running left to right. *Set per screen.*
* **Show vertical grid lines**: Draws grid lines at the ticks of the time axis.
* **Show y-axis track labels**: Draws the axis line along the track names; the names themselves always show.
* **Show tooltips**: Shows a tooltip with category, start and end time when hovering a block.
* **Enable crosshair**: Shows crosshair lines with axis labels following the pointer. *Set per screen.*

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.heisenware.com/reference/widgets/display/timeline.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
