URL-Synced Variables

Two Sources of URL Variables

1. Route Parameters (`route.*`)

Route parameters are URL path segments defined in the AppPage route pattern. They are automatically available as {{ route.paramName }} tokens:

// AppPage route: /leads/:id
// URL: /app/crm/leads/lead-456

{{ route.id }}  →  "lead-456"

2. URL-Synced App Variables (Query Params)

App variables declared with syncToUrl: true are automatically reflected in and read from URL query parameters:

// App config — URL-synced variable
"variables": {
  "filterStatus": {
    "type": "string",
    "initialValue": "all",
    "syncToUrl": true   // ← enables URL sync
  }
}
// When filterStatus = "active", URL becomes: /app/crm/leads?filterStatus=active
// When user shares this URL, the recipient sees the same filtered view

How URL Sync Works

App Loads with URL

The URL Variable Syncer reads all query params and sets matching URL-synced variables to the URL values on page load. If a query param is absent, the variable uses its initial value.

Variable Changes at Runtime

Set Variable action changes a URL-synced variable. The URLVariableSyncer updates the URL query param immediately (using history.pushState — no page reload).

Shareable / Reload-Safe

User copies the URL and shares it. The recipient loads the URL with the same query params — the app initializes with the same filter state. Back/forward browser navigation also restores variable state.

Navigating with Query Params

The Navigate action can include query params that map to URL-synced variables:

// Navigate to leads list with pre-set filter
{
  "type": "navigate",
  "target": "/leads",
  "params": {
    "filterStatus": "active",
    "filterOwner": "{{ context.userId }}"
  }
}
// URL: /app/crm/leads?filterStatus=active&filterOwner=user-jane
// filterStatus and filterOwner variables initialize from these params

URL Sync vs. Route Params

Use route parameters (/leads/:id) for resource identity — the thing being viewed. Use URL-synced variables (query params) for UI state — filters, sort order, pagination. Route params change the AppPage rendered; query params change how the same AppPage displays data.

← App Variables Next: Context Tokens →