Action

Definition & Purpose

An Action models something an actor can initiate from a screen (e.g. clicking a submit button, pressing retry, submitting a form, or receiving a webhook event). Actions strictly belong to screens and contain one or more relation outcomes.

Action Schema & Properties

Action objects declare human labels, initiating actors, and relations:

• name (string, optional) — Human-readable trigger label (e.g. Submit Credentials).
• actor (string, optional) — ID of the actor initiating the trigger (e.g. customer).
• relations (object, REQUIRED) — Dictionary of transition outcomes keyed by relation ID.

Address Syntax & Examples

Action addresses append .actions.action_id to the owning screen address:

1Address format:
2screen_id.actions.action_id
3
4Real-world domain address examples:
5- checkout.actions.retry_payment
6- sign_in.actions.submit_credentials
7- billing.actions.cancel_subscription
8- cancellation_review.actions.accept_retention

Directed Edge Presentation

In Canvas view, Actions render as interactive handles on screen cards. Dragging from an action handle creates relation directed edges pointing to destination screens.

Complete Valid Example

Here is a complete screen action declaring actor, label, and dual relation outcomes:

1screens:
2  checkout:
3    name: Checkout Surface
4    actions:
5      retry_payment:
6        name: Retry Failed Payment
7        actor: customer
8        relations:
9          success:
10            to: billing
11            state: active
12            when: Payment gateway approves card
13          declined:
14            to: checkout
15            state: payment_failed
16            when: Payment gateway declines card again

What an Action Does NOT Mean

A UXDL Action is NOT an HTTP REST API route, NOT an onClick handler function, and NOT a Redux action object. It describes an observable user or system trigger.

Connected Primitives & Best Practices

• Actor — References the human or system participant triggering the action.
• Relation — Every action MUST declare at least one relation outcome dictionary.
• Duality — Actions should specify both success and failure/declined relations where recovery is possible.