> 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/value-box.md).

# Value Box

Displays a single live value with number/date formatting and JSON tree rendering for objects

<figure><img src="https://3495989837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE5Ketpww1s7TauSAJrJ8%2Fuploads%2Fgit-blob-1afcb2f3a02c11f40f447cec81ef44c544dbf578%2Fwidget-value-box.png?alt=media" alt="Value boxes showing bottles filled, OEE and an oven temperature in red, and a value box rendering the current order as a JSON tree" width="1258"><figcaption></figcaption></figure>

A value box shows one live value, big and clear: a count, a percentage, a temperature, a text. Numbers and dates take a format, a prefix and a suffix, so 18460 reads as 18,460 and 193.6 as 193.6 °C. Your logic can change the text color, for example to red when a limit is crossed. Hand it an object or a list and it renders a JSON tree the user can fold, which helps while you build and test.

**Good for:** key figures on dashboards, current setpoints and readings, a quick look at what an executor returns.

## 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" %}
**`value`** (from an output, `string | number | boolean | object | array | null`): Accepts various data for display. Handles strings, numbers, objects and images.

<details>

<summary>Example</summary>

```json
42.7
```

</details>

**`clear`** (from an output, `boolean`): Truthy values clear the displayed value.

<details>

<summary>Example</summary>

```json
true
```

</details>

**`textColor`** (from an output, `string`): CSS color for the displayed text (overrides the configured color).

<details>

<summary>Example</summary>

```json
"#62a378"
```

</details>
{% endtab %}

{% tab title="Emits" %}
**`onClick`** (into an input, `string | number | boolean | object | array | null`): Writes the currently displayed value when the box is clicked. Exceptional use only - click semantics belong to buttons; a click that must carry a value is a button firing an executor whose input holds it.

**`onClick`** (fires a trigger): Triggers the linked executor when the box is clicked.
{% 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>Look &#x26; feel</summary>

* **Font size**: Font size of the shown value in px. Range 6 to 42. *Set per screen.*
* **Font weight**: Weight of the value text. Choices: Normal, Bold, Bolder.
* **Horizontal alignment**: Horizontal position of the value inside the box. Choices: Left, Center, Right.
* **Vertical alignment**: Vertical position of the value inside the box. Choices: Top, Middle, Bottom.
* **Text color**: Color of the value text; empty or auto keeps the theme's, a bound textColor overrides it.
* **Format**: Formats numbers and dates for display, with a number or a date format; empty shows the value as it is. Choices: Fixed point, Decimal, Currency, Percent, Large number, Thousands, Millions, Billions, Trillions, Exponential, Short date, Long date, Short time, Long time, Short date & time, Long date & time, Month & day, Month & year, Quarter & year, Day, Day of week, Month, Year, Quarter, Hour, Minute, Second, Millisecond.
* **Prefix**: Text put in front of the shown value; objects and images ignore it.
* **Suffix**: Text put after the shown value; objects and images ignore it.
* **Placeholder**: Text shown in gray italics while no value has arrived or after clear; empty by default. An empty string from the backend shows an empty box.

</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/value-box.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.
