> For the complete documentation index, see [llms.txt](https://docs.chirpwireless.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chirpwireless.io/dashboards/adding-widgets/conditions.md).
# Conditions
Conditions are per-metric color rules that turn a raw sensor reading into visible meaning. Instead of looking at a number and deciding whether it's good or bad, the widget does that for you — a green pin means comfortable, a red pin means check it now, a yellow marker means getting close to the limit. You define what those colors mean for each sensor in each place it's used.
A temperature sensor in the living room should be green at 18–24°C. The same type of sensor watching a fridge should be green at 2–5°C. Different place, different meaning, completely different conditions — even though the data looks the same.
## Which widgets use conditions
Conditions are available for **Last Data** and **Image** widgets. Each metric in these widgets has its own set of conditions, configured independently.
The **Chart** widget uses a different approach — per-metric color picker and threshold bands on the graph. See [Chart Widget](/dashboards/adding-widgets/chart-widget.md) if you're working with a Chart.
**Note on metric types:** Both the Image and Last Data metric selectors surface numeric sensors only (INTEGER and FLOAT types). Number conditions are the practical path for both widgets. The conditions modal also exposes String and Boolean data type options — these are described below — but they require a widget that can select a sensor of those types, which is not currently the case for Last Data or the Image widget.
## How to open the Conditions modal
1. Open the widget's settings and go to the **Datasource** tab.
2. Find the metric row for the sensor you want to configure.
3. Tap the **Conditions button** — it's labeled **"Conditions: N"** where N is the number of conditions currently set.
4. The Conditions modal opens.
## What the Conditions modal contains
**Title:** "Conditions" / **Subtitle:** "The conditions set first will be considered as a priority"
**Header (applies to the whole metric):**
* **Device metric** — Read-only. Shows which sensor this modal is for.
* **Unit** — A free-text box for the unit shown next to the value on the tile (like `42 cm`). Type **whatever unit you want** — `mm`, `cm`, `m`, inches, `L`, `°C`, anything. It's not limited to a list and it's not a percentage unless you make it one. It starts from the sensor's own unit, and you can change it to suit. The **From / To** numbers in your rules are in this unit (so `From 0 To 30` means 0–30 of whatever you set here).
* **Icon** — Pick or change the icon for this metric.
* **Default color** — The color used when no condition matches. This is the only place to set the metric's base color.
**Conditions list:** Each condition has:
* **Condition name** *(required)* — A label like "Comfortable", "Warning", or "Critical". Must not be empty.
* **Data type** — Number, String, or Boolean (see below)
* **Value fields** — Depend on the data type
* **Color** — The color to show when this condition matches
* **Delete** — Remove this condition
**Add condition** — Tap to add a new condition. New conditions default to: name "Condition N", type Number, From 0, To 100, primary color.
There's no limit on the number of conditions you can add.
**Save** (disabled while any validation error exists) / **Cancel**
## Priority: first match wins
Conditions are evaluated top to bottom. The **first condition in the list that matches the current reading** determines the color. Order matters.
If your sensor reads 7°C and you have:
1. "Normal" — Number, From 2, To 8 — green
2. "Warning" — Number, From 8, To 12 — yellow
The reading 7°C matches condition 1, so green is shown. Condition 2 is not evaluated.
To change priority, reorder the conditions in the list.
## Value fields by data type
### Number
**From** and **To** fields — both are optional. Either can be left empty to create an open-ended range:
* **Empty From** — matches any value below To (no lower limit)
* **Empty To** — matches any value above From (no upper limit)
* **Both filled** — From must be ≤ To
Examples:
* From: 18, To: 24 → matches readings between 18 and 24
* From: 30 (no To) → matches any reading 30 and above
* (no From), To: 5 → matches any reading 5 and below
### Number conditions — on/off and open/closed states
Many sensors report binary state as a number: 1 when something is active or open, 0 when it is off or closed. Number conditions map these values to meaningful labels and colors:
* Condition "On" — Number, From 1, To 1 — yellow (or your chosen color)
* Condition "Off" — Number, From 0, To 0 — grey
Examples using this pattern:
* Light sensor: 1 = "On" (yellow), 0 = "Off" (grey)
* Contact sensor (door): 1 = "Open" (red), 0 = "Closed" (green)
* Leak sensor: 1 = "Leak detected" (red), 0 = "Clear" (green)
The same Number condition type handles all of these. The difference is only in the labels and colors you assign.
### String
A single **Value** text field. Matches the reading exactly, case-sensitive. Available in the conditions modal but requires a widget that surfaces a String-type sensor — Last Data and Image widget selectors do not surface String sensors.
### Boolean
A **True / False** dropdown. Matches the reading exactly. Available in the conditions modal but requires a widget that surfaces a Boolean-type sensor — Last Data and Image widget selectors do not surface Boolean sensors.
## Color fallback hierarchy
1. **Matched condition color** — The color of the first matching condition
2. **Default color** — The color set in the modal header (applies when no condition matches)
3. **Platform default** — Applied when no default color is set in the modal
## Examples
### Keeping something topped up
Say you've got a sensor on something you want to keep full — a rainwater tank, the salt in a water softener, a heating-oil tank — reading how full it is in whatever unit suits you. Set that in the **Unit** box (it takes anything — `cm`, `m`, inches, liters…); here we'll use **centimeters** of depth. Three rules then turn that into a clear "do I need to refill?" status, and since the **first matching rule wins**, list the most urgent one first:
* **Refill** — Number, From 0, To 30 — red
* **Getting Low** — Number, From 30, To 50 — amber
* **Normal Level** — Number, From 50, To 100 — green
The tile stays green while it's well stocked, turns amber as it runs down, and goes red as soon as it drops into the refill zone — so you top it up before it runs out. Want a nudge on your phone too? Add an [alert](/alarm.md) on the same level.
### Number conditions — temperature in two contexts
**Living room sensor:**
* "Comfortable" — From 18, To 24 — green
* "A bit cool" — From 15, To 18 — yellow
* "Cold alert" — (no From), To 15 — red
**Fridge sensor (same sensor type, completely different meaning):**
* "Normal" — From 2, To 5 — green
* "Check fridge" — From 5 (no upper limit) — red
The readings look the same — both are temperatures in °C. The conditions are completely different because "2°C in a fridge" is fine, while "2°C in the living room" is an emergency.
### Number conditions — open-ended bounds for a tank level
A water tank sensor reports its fill level (here in percent, but you choose the unit):
* "Critical" — (no From), To 20 — red
* "Low" — From 20, To 50 — yellow
* "Good" — From 50 (no upper limit) — green
The first condition catches everything below 20%. The last catches everything above 50%. There's no need to specify exact upper/lower limits for every range.
### Number conditions — any numeric reading
The system doesn't care what the number represents. The same pattern works for:
* Battery level (%, 0–100)
* Soil moisture (%, 0–100)
* CO₂ level (ppm)
* Tank volume (liters or gallons)
* Any sensor that reports numbers
The meaning and the thresholds are yours to define.
### String conditions — device status sensor
A sensor that reports text values like "OK", "WARNING", or "FAULT":
* "OK" — String, Value: OK — green
* "Warning" — String, Value: WARNING — yellow
* "Fault" — String, Value: FAULT — red
No math involved. The widget reads the string, matches it exactly, and shows the right color.
### Boolean conditions — binary state sensors
**Motion sensor:**
* "Motion detected" — Boolean, True — orange
* "Clear" — Boolean, False — green
**Leak detector:**
* "Leak detected" — Boolean, True — red
* "Clear" — Boolean, False — green
**Pump running:**
* "Running" — Boolean, True — blue
* "Idle" — Boolean, False — grey
Any binary sensor works the same way: pick a color for each state and a label that makes sense in context.
## See also
* [Last Data Widget](/dashboards/adding-widgets/last-data-widget.md) — Use conditions to color sensor readings and gauges
* [Image Widget](/dashboards/adding-widgets/image-widget.md) — Use conditions to color the pins on your image
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.chirpwireless.io/dashboards/adding-widgets/conditions.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.