Relation

Definition & Purpose

A Relation defines where a user or system lands after an action occurs. It acts as a directed edge in the UXDL graph, linking an action to a destination screen, state, external URL, or terminal end-point.

Three Destination Forms

Every relation MUST declare exactly one of the three destination forms:

• 1. 'to' (string) — Target screen ID, with optional target 'state' ID.
• 2. 'external' (string) — External URL outside the modeled experience (e.g. Stripe checkout URL).
• 3. 'end: true' (boolean) — Intentional terminal flow screen (e.g. account deleted).

Address Syntax & Examples

Relation addresses append .relations.relation_id to the action address:

1Address format:
2screen_id.actions.action_id.relations.relation_id
3
4Real-world domain address examples:
5- checkout.actions.retry_payment.relations.success
6- sign_in.actions.submit.relations.invalid_password
7- billing.actions.cancel.relations.review_modal

Flowchart Edge Representation

In Canvas view, relations render as directed arrows connecting actions to target screens or states, annotated with natural-language 'when' conditions.

Complete Valid Example

Here is an action with three relations demonstrating all three destination forms:

1actions:
2  submit_order:
3    name: Finalize Order
4    relations:
5      internal_success:
6        to: order_confirmation
7        state: confirmed
8        when: Internal card payment succeeds
9      external_gateway:
10        external: "https://checkout.stripe.com/c/pay/123"
11        when: User selects PayPal / external gateway
12      terminal_cancel:
13        end: true
14        when: Buyer cancels session permanently

What a Relation Does NOT Mean

A UXDL Relation is NOT a database foreign key constraint, NOT a Next.js router.push() call, and NOT an HTTP 302 redirect header. It describes a graph transition outcome.

Connected Primitives & Best Practices

• Action — Every relation MUST belong strictly to an action.
• Single destination rule — Declaring multiple destination forms (e.g. both 'to' and 'external') is a structural error.
• Natural language 'when' — Use concise conditions explaining when the relation branch fires.