# States

> States conditionally show or hide parts of a widget based on data values. Give a state a name matching a tag in your widget code, pick a visibility mode, and build conditions with operators, AND/OR connectors, and nested groups.

**States** conditionally show or hide parts of a widget based on its data values. Each state wraps a section of your widget and decides — from the current data — whether that section renders. Use them to flip a form to a thank-you after submit, show a loading skeleton, reveal an error, or tailor what a customer sees to their data.

> **WHERE TO MANAGE THEM:** States live in the widget builder's **States** tab. A state's **name** must match a tag that wraps content in your widget code — for example a state named `Loading` controls the markup inside `<Loading>…</Loading>`.

## How a state works

A state has three parts:

- **Name** — matches the tag that wraps the content it controls in your widget code (e.g. `<Loading>…</Loading>`, `<Submitted>…</Submitted>`).
- **Visibility mode** — how the wrapped section behaves: **Always visible**, **Always hidden**, or **Conditional**.
- **Conditions** — for a Conditional state, the rules (evaluated against the widget data) that decide whether the section shows.

| Visibility mode | Behavior |
| --- | --- |
| Always visible | The wrapped section always renders. |
| Always hidden | The wrapped section never renders. |
| Conditional | The section renders only when its conditions are met by the current data. |

> **NAME = TAG:** Wrap the markup you want a state to govern in a tag whose name matches the state. The renderer shows that section only when the state's conditions pass.

## Conditions

A **condition** compares a data field against a value using an operator. Add one or more conditions to a Conditional state.

| Operator | Matches when the field… |
| --- | --- |
| equal to | equals the value. |
| not equal to | does not equal the value. |
| contains | contains the value. |
| not contains | does not contain the value. |
| greater than | is greater than the value. |
| less than | is less than the value. |
| is empty | has no value. |
| is not empty | has a value. |

## Combining conditions

Stack multiple conditions and join them with **AND / OR** connectors. The connector is set per condition from the second condition on — so each row after the first chooses whether it joins the previous ones with AND or OR.

- **AND** — every joined condition must be true.
- **OR** — any one of the joined conditions can be true.

## Nested condition groups

For compound logic, nest a **condition group** — a set of conditions that evaluates as a unit, like parentheses in a formula. Groups let you express rules that mix AND and OR unambiguously:

```text
(status = active AND role = admin)
OR
(status = active AND role = editor)
```

> **TIP:** Build each parenthesized clause as its own group, then join the groups with an OR connector — exactly as written above.

## Multiple active states

A widget can have **several states active at once** — each one controls its own wrapped section independently. A loading section, an error section, and a results section can all be states on the same widget, and the data decides which combination shows at any moment.

## What's next

- [Code editor](/docs/widgets/code-editor) — Wrap sections in state tags and preview them.
- [Components](/docs/widgets/components) — The components you place inside each state.
- [Widgets overview](/docs/widgets/overview) — How states fit into a widget.