UI events

UI events enable frontend-side data transformations directly on UI components, eliminating the need for server roundtrips when updating local data. Configure event expressions that evaluate at runtime to create responsive, performant user interfaces.

Available starting with FlowX.AI 5.3.0: UI Events enable real-time interaction handling directly within Reusable UI Templates, allowing you to capture user interactions and respond immediately without process execution.

Overview

UI events allow you to define JavaScript expressions that execute when users interact with UI components. Unlike UI actions that communicate with the backend, UI events operate entirely on the client side to update local data instantly.

UI events were introduced to reduce UI load time and address related UX issues. The expressions are evaluated by the SDKs at runtime on the front-end side, leading to faster load times. They are intended for more complex business logic than what is handled by simple hide expressions or computed expressions.

No server roundtrip

Update data locally without waiting for backend responses

Instant feedback

Provide immediate UI updates as users interact with components

Simplified logic

Replace complex business rule chains with simple expressions

Computed expressions

Use JavaScript to calculate and transform data on the fly

Key characteristics

Characteristic	Description
Client-side evaluation	Expressions are executed on the client side by the SDKs, not on the server
Action timing	Evaluated right before executing a UI action (if one is configured), but not exclusive to actions
Local data updates	Updated variables are stored locally on the UI and not available on the process engine’s server data store until a submit action is executed
Data source requirements	Must rely only on properties already displayed on the screen; if a property used in the expression is not configured on the page to be sent from backend to frontend, the expression will fail
Component availability	Available for form elements, buttons, and collection prototypes (see supported components)

Data availability: UI event expressions can only access data that is already being sent from the backend to the frontend for display on the current page. If you reference a property that isn’t configured to be sent to the UI, the expression will fail.

Traditional approach vs UI events

Previously, updating derived values required a multi-step process:

1. User changes input

   User modifies a form field value

2. UI action triggers

   A UI action sends data to the backend

3. Business rule executes

   Server-side business rule calculates new values

4. Data returns to UI

   “Send data to user interface” action pushes updated data back

With UI events, steps 2-4 are replaced by a single client-side expression that evaluates instantly.

---

Configuring UI events

UI events are configured in the UI Designer through a dedicated section located above the UI Actions panel.

Event configuration structure

Each event configuration consists of:

• Event trigger: The user interaction that initiates the expression (e.g., onChange, onClick)
• Expression: A JavaScript computed expression that calculates and returns new data

Platform configuration

UI events are stored in the component’s platformDisplayOptions under the events property:

{
  "platformDisplayOptions": {
    "platform": "generic",
    "flowxProps": {
      "events": [
        {
          "event": "onChange",
          "expression": "const prc = ${client.debt} / ${client.income};\nreturn {\n  \"client\": {\n    \"debtPrc\": prc\n  }\n}"
        }
      ]
    }
  }
}

UI events are available in both the Process UI Designer and the Reusable UI Templates Designer.

---

Writing event expressions

Event expressions use the same JavaScript syntax as computed values, with one key difference: instead of returning a single value, event expressions return an object that updates the local data store.

Expression syntax

// Access process parameters using ${} syntax
const calculatedValue = ${client.debt} / ${client.income};

// Return an object to update local data
return {
  "client": {
    "debtPercentage": calculatedValue
  }
}

Comparison with business rules

Aspect	Business Rule	UI Event Expression
Input access	${} syntax	${} syntax
Logic language	Python, JavaScript, MVEL	JavaScript only
Output syntax	output.put(key, value)	return { }
Execution	Server-side	Client-side (SDK)
Latency	Network roundtrip	Instant

Expression examples

Calculate percentage

Calculate debt-to-income ratio when income or debt changes:

const prc = ${client.debt} / ${client.income};
return {
  "client": {
    "debtPrc": prc
  }
}

Conditional formatting

Set a status based on a threshold:

const amount = ${application.loanAmount};
const status = amount > 100000 ? "high" : "standard";
return {
  "application": {
    "riskCategory": status
  }
}

String transformation

Format and combine user input:

const first = ${customer.firstName} || "";
const last = ${customer.lastName} || "";
return {
  "customer": {
    "fullName": first + " " + last,
    "initials": first.charAt(0) + last.charAt(0)
  }
}

Array operations

Calculate totals from a list:

const items = ${order.items} || [];
const total = items.reduce((sum, item) => sum + item.price, 0);
return {
  "order": {
    "totalAmount": total,
    "itemCount": items.length
  }
}

---

Supported components and events

Each UI component type supports specific event triggers:

Form elements (onChange)

Component	Event	Trigger Description
Input	onChange	When the input value changes
Text area	onChange	When the text content changes
Select	onChange	When a selection is made
Multi select	onChange	When selections change
Date picker	onChange	When a date is selected
Slider	onChange	When the slider value changes
Radio	onChange	When a radio option is selected
Checkbox	onChange	When the checkbox state changes
Segmented button	onChange	When a segment is selected
Switch	onChange	When the switch is toggled

Interactive components (onClick)

Available starting with FlowX.AI 5.6.0

Component	Event	Trigger Description
Button	onClick	When the button is clicked
Collection Prototype	onClick	When a collection item is clicked

The onClick expression evaluates synchronously before any UI action configured on the same component. This lets you update local data (e.g., set the selected item’s ID) right before the action fires.

Example — set selected item on collection click:

const selectedId = ${items.currentItem.id};
return {
  "selection": {
    "activeItemId": selectedId
  }
}

Future enhancement: An improvement being considered is the ability to reuse event expressions across multiple elements, as many behaviors depend on multiple elements that should share the same behavior.

---

UI events in Reusable UI Templates

UI events work within Reusable UI Templates. When using events in templates, ensure that any keys referenced in the expression are properly mapped through the template’s input parameters.

Input mapping requirements

For an expression like:

income = ${client.income}
debt = ${client.debt}

if (income && debt) {
    return {
    "client": {
        "ratio": ${client.debt} / ${client.income}
    }
    }  
} else {
    return {}
}

The template must have client.debt and client.income configured as input parameters to receive values from the parent process context.

When designing reusable templates with UI events, document which input parameters are required for the events to function correctly.

---

Runtime behavior

Execution flow

When a trigger event occurs:

1. Event triggered

   User interaction fires the configured event (e.g., onChange)

2. Expression evaluated

   The SDK evaluates the JavaScript expression synchronously

3. Local data updated

   The returned object merges into the local data store

4. UI refreshed

   Components bound to the updated data re-render automatically

Coexistence with UI actions

UI events and UI actions can be configured on the same component. When both are present:

1. The UI event expression evaluates first (right before the action)
2. The UI action executes after the event completes

This allows you to perform local calculations before sending data to the backend.

Local vs server data

Variables updated by UI events remain local to the UI until a submit action is executed. The process engine’s server data store does not receive these updates until data is explicitly submitted.

This means:

• Immediate UI updates without server latency
• Multiple calculations can be performed before submitting
• Server-side data only updates when you trigger a data submission action

UI event expressions are synchronous computations. Avoid complex operations that could block the UI thread.

---

Best practices

Keep expressions simple

UI events are designed for lightweight transformations. For complex business logic, continue using server-side business rules.

// ✅ Good: Simple calculation
const total = ${cart.subtotal} * 1.1;
return { "cart": { "totalWithTax": total } }

// ❌ Avoid: Complex async operations or heavy computations

Ensure data is available on the page

UI event expressions can only access data that is already configured to be sent from the backend to the frontend. Before using a property in an expression:

• Verify the property is bound to a UI component on the current page
• Ensure the data is included in the page’s data context
• Test with actual data to confirm availability

Handle missing data gracefully

Always account for potentially undefined values:

// ✅ Defensive coding
const income = ${client.income} || 0;
const debt = ${client.debt} || 0;
const ratio = income > 0 ? debt / income : 0;
return {
  "client": {
    "debtRatio": ratio
  }
}

Use meaningful return structures

Return objects should mirror your data model structure:

// ✅ Matches data model hierarchy
return {
  "application": {
    "calculations": {
      "monthlyPayment": payment,
      "totalInterest": interest
    }
  }
}

Test expressions thoroughly

Before deploying, verify your expressions handle:

• Valid input values
• Empty or null inputs
• Edge cases (zero, negative numbers, empty strings)
• Different data types

---

Troubleshooting

Expression not evaluating

Symptoms: Data doesn’t update when interacting with the component

Solutions:

• Verify the event type matches the component (e.g., onChange for inputs)
• Check that process parameter syntax uses ${} correctly
• Ensure the expression includes a return statement
• Confirm the component has the event properly configured

Property not available error

Symptoms: Expression fails because a referenced property is undefined

Solutions:

• Ensure the property is configured on the current page to be sent from backend to frontend
• Verify the property is bound to a UI component or included in the page’s data context
• Only rely on properties that are already being displayed on the screen
• Check that nested properties exist in the data model

Return value not applied

Symptoms: Expression runs but data doesn’t change

Solutions:

• Verify the return object structure matches your data model
• Check for JavaScript syntax errors in the expression
• Ensure you’re returning a valid object, not undefined or null

Performance issues

Symptoms: UI feels sluggish during interactions

Solutions:

• Simplify complex expressions
• Avoid array operations on large datasets
• Move heavy computations to server-side business rules

---

On Load event

Available starting with FlowX.AI 5.5.0

The On Load event executes actions automatically when a UI Flow screen loads, enabling data initialization and setup operations without user interaction.

The onLoad event triggers when a screen (Page, Zone, Tab Bar, or Modal) is rendered for the first time in a session. Unlike form element events that respond to user interaction, On Load runs automatically during screen initialization.

Modal support available starting with FlowX.AI 5.6.0

Modal components inside UI Flows now support On Load events and the Start Workflow UI action, enabling data fetching when a modal opens.

Supported components

Component	Event	Trigger Description
Page	onLoad	When the page is first rendered
Zone	onLoad	When the zone is first rendered
Tab Bar	onLoad	When the tab bar is first rendered
Modal	onLoad	When the modal is first rendered

Key behavior

• Triggers once per session by default — The On Load event fires only once per component per session to prevent duplicate executions during normal navigation (e.g., back/forward, breadcrumbs)
• Re-triggers on Navigate To — When a Navigate To action targets a screen, the destination screen’s On Load event re-fires. This ensures data is re-initialized each time a user explicitly navigates to that screen
• Re-triggers on intent navigation — When an AI chat agent navigates a user to a screen via intent-based navigation, the destination screen’s On Load event re-fires, even if the component is already mounted
• Workflow support — On Load events can trigger Start Workflow actions for data fetching during screen initialization

Configuration

1. Select the screen component

   In the UI Designer, select the Page, Zone, Tab Bar, or Modal component that should trigger actions on load.

2. Add On Load event

   In the Events section, add a new event and select onLoad as the trigger type.

3. Configure the action

   Define the action to execute when the screen loads. Common use cases:

   • Start Workflow — Fetch initial data from an API
   • UI event expression — Initialize computed values

Example: Initialize screen data

Use On Load to fetch data when a dashboard screen loads:

1. Add a Page component with an onLoad event
2. Configure a Start Workflow action to call a data-fetching workflow
3. Map the workflow output to UI Flow data keys for display

Avoid long-running operations in On Load events, as they block screen rendering until complete. Use loading states to provide feedback during data fetching.

---

On Display event

Available starting with FlowX.AI 5.6.0

The On Display event re-triggers actions every time a screen becomes visible, including after navigation and modal dismissal.

The onDisplay event triggers whenever a component becomes visible — on initial render, when navigating back to a screen, or when a modal is dismissed. Unlike On Load (which fires once per session), On Display fires every time the component is displayed.

Supported components

Component	Event	Trigger Description
Page	onDisplay	Every time the page becomes visible
Zone	onDisplay	Every time the zone becomes visible
Tab Bar	onDisplay	Every time the tab bar becomes visible

On Display vs On Load

Aspect	On Load	On Display
When it fires	Once, when the component first mounts	Every time the component becomes visible
Re-triggers on navigation	No	Yes — fires when returning to the screen
Re-triggers on modal dismiss	No	Yes — fires when a modal closes
Use case	One-time initialization	Refresh data on every view
Supported actions	Start Workflow	Start Workflow

Configuration

1. Select the screen component

   In the UI Designer, select the Page, Zone, or Tab Bar component.

2. Add On Display event

   In the Events section, add a new event and select onDisplay as the trigger type.

3. Configure the action

   Define the Start Workflow action to execute when the screen is displayed. Use this for data refresh operations.

Example: Refresh data on navigation

Use On Display to re-fetch data whenever a user returns to a screen:

1. Add a Page component with an onDisplay event
2. Configure a Start Workflow action to call a data-fetching workflow
3. Each time the user navigates to the page (or dismisses a modal), the workflow re-runs and refreshes the displayed data

Use On Load for one-time initialization (e.g., setting default values) and On Display for data that should refresh on every visit (e.g., dashboard metrics, list views).

---

Related resources

UI Actions

Configure backend interactions triggered by UI components

Dynamic & Computed Values

Learn about JavaScript expressions for dynamic UI properties

Reusable UI Templates

Create modular UI components with event support

Form Elements

Explore form components that support UI events