State

Definition & Purpose

A State describes a distinct, observable condition of a screen. While a screen defines where a user is, a state defines what condition that surface is currently displaying (e.g. default, empty, loading, error, past_due).

Compact vs Expanded Format

UXDL supports two syntax formats for declaring states:

1# Compact Format (String description):
2states:
3  default: Ready for user input
4  payment_failed: Gateway declined card
5
6# Expanded Format (Object with metadata):
7states:
8  payment_failed:
9    name: Payment Declined
10    metadata:
11      analytics_id: "evt_pay_failed"
12      error_code: "card_declined"

Address Syntax & Examples

State addresses append .states.state_id to the owning screen address:

1Address format:
2screen_id.states.state_id
3
4Real-world domain address examples:
5- checkout.states.payment_failed
6- billing.states.past_due
7- sign_in.states.invalid_credentials
8- dashboard.states.empty_workspace

Flowchart Node Presentation

In Canvas view, states render as variant tags inside their parent screen card. When targeted by a relation arrow, the edge connects directly to the specific target state tag.

Complete Valid Example

Here is a screen with 4 distinct states representing a payment lifecycle:

1screens:
2  checkout:
3    name: Checkout Surface
4    type: page
5    states:
6      default: Ready for credit card input
7      processing: Submitting payment transaction
8      payment_failed: Gateway declined card (grace period active)
9      session_expired: Security token timed out

What a State Does NOT Mean

A UXDL State is NOT component local state (React useState), NOT a Redux/Zustand store object, and NOT a database row column value. It describes an observable user-facing surface variation.

Connected Primitives & Best Practices

• Screen — Every state MUST belong to exactly one parent screen.
• Relation — Relations target specific states using 'to: screen_id' and 'state: state_id'.
• Contextual Linter — The linter flags screens missing error or empty state coverage.