Tap actions

Tap actions turn a data piece or a component from something you just look at into something you can use: tap to refresh data, ask a question, open a link, send a command, run a bit of logic — or chain several of these together.

Add and edit them from Events on the data piece (data piece editor with nothing selected) or on a component. Each event row shows how many actions are on. The switch on the right turns that event on or off. Tap the row to open its actions. Inside that screen, tap an action to configure it, drag the handle to reorder it, and swipe it right to left to delete it.

A new control may already have Apply value:

Add a send after those actions, or edit the expression in Value if your on and off values are different.

When you need Apply value. Each action passes its result to the next one, and what happens to the last result depends on where the list is:

Apply value on a component changes only that component. Other components that use the same data source keep showing the source value. To update them all, put the actions on the data piece. Apply value never changes the data source or the device.

If the data piece list is on and has at least one action that is on, a tap on that card runs the data piece list. Components on that card — including toggles and buttons — do not receive the tap.

A group can have tap actions too. If that list is on and has at least one action that is on, a tap on the group runs those actions and does not reach components inside the group. If the group has no tap actions, taps go through to those components.

On long press

Many components have On long press. A long press runs it.

The run starts from the current value. It does not flip a switch, and it does not store the pipeline value on its own. Add Apply value when you want that value kept.

It does not also run On tap or On change. On a Data table, a long press on a row uses that row. On a Date picker or Time picker, a long press does not open the picker.

Slider, Circular slider, Knob, Range, Color picker, Joystick, Text input, Text field, and Highlight editor do not have this list. Holding a slider is how you drag it.

If the data piece list is on and has at least one action that is on, a long press still reaches the component under your finger. A tap on the card still runs the data piece list.

On tap hold and On tap release

Use these to steer something while you hold a button, for example a robot or a toy car.

On tap hold runs as soon as you press, then again while your finger stays down. Interval (ms) sets how often: 100 by default, at least 20. A new run waits until the previous one has finished, so runs never pile up. On tap release runs once when you let go, after the last run has finished. Put your stop command there. Example: MQTT send with forward in On tap hold and MQTT send with stop in On tap release.

The hold goes on if your finger slides off the component. It also ends when you edit the layout, leave the screen, or the app goes to the background, and On tap release still runs.

While either list has an action that is on, pressing that component runs only these lists: On tap and On long press don't run. On a group, the hold covers the whole group. You can hold several components at once.

These lists can't show anything on screen, so actions that ask a question, show a message, or open a screen are not offered. In scripts, ctx.tick counts the runs from 0 and ctx.heldMs is how long you have been pressing. On tap release gets ctx.heldMs and ctx.ticks.

On change and On changed

Slider, Circular slider, Knob, Range, Color picker, and Joystick have two lists.

On change actions pipe runs while you drag a handle. On a Color picker, value is the color as #RRGGBB. If you move faster than the actions finish, the value where you let go still runs. Debounce in this list starts again when the handle moves, and only the latest value continues. That is how Debounce works in a transformer list.

On changed actions pipe runs once when you let go. On a Knob it runs only if the drag changed the value. A new Slider, Circular slider, Knob, Range, or Color picker already has Apply value (From pipeline) on that list.

On a Joystick, value is an object with x and y, each from −1 to 1 (right and up are positive): use {{ value.x }} and {{ value.y }}.

On change actions pipe runs again and again while you hold the stick, as often as Interval (ms) says, and once more with 0 and 0 when you let go. On changed actions pipe runs once when you let go, with 0 and 0. A new Joystick starts with both lists empty: put the drive command in On change actions pipe and the stop command in On changed actions pipe.

Text input, Text field, and Highlight editor have only On change actions pipe. It runs as you type. They have no tap list. Finishing the field or leaving it does not run actions. A new one of these does not start with Apply value.

If the data piece list or a group list is on and has at least one action that is on, the drag or the typing never reaches the control.

A control that uses a data source shows the source's value, but moving it does not change the source. Apply value only changes what the control shows. To change the device or the server, add MQTT send, HTTP request, or Trigger data destination to On change, On changed, or On tap. See What interactive components send.

What happens when you tap

  1. Starting point. The run starts from the current pipeline value, not a leftover from an earlier tap. Routix Dash also keeps two snapshots available for the whole run — raw and transformed — plus a shared ctx you can read and write across actions.
  2. Order. Actions run one after another, never at the same time. Whenever an action produces a result, that becomes the new value for the next action.
  3. Enable or disable. Each action can be turned off without deleting it; disabled actions are skipped. Each action can also be Always run, Run if, or Do not run if. The condition is a {{ }} template. Run if skips that row when the condition is not met. Do not run if skips it when the condition is met. If the condition cannot be evaluated, that row is also skipped, and the list continues — that is not a failure.
  4. While it runs. Automatic background refreshes of the underlying data source pause for the duration, so the run always sees a stable value. Refreshes you trigger yourself still work. A second tap while this list is still running is ignored.
  5. Cancelling. If you dismiss a prompt (like a text or selection dialog) without confirming, Routix Dash can stop the rest of the run right there. Stop pipeline skips later rows without a failure. In a Lua or JavaScript action, set ctx.stopPipeline = true for the same effect. A wait animation stays until this tap list finishes; Stop wait animation can hide it earlier. Incoming data from the source does not clear it.
  6. If an action fails. The rest of the run stops. The wait indicator still clears when the list finishes.
    • Stop pipeline if failed is on unless you turn it off. A server error, a timeout, or a lost connection then stops the rest of the list. The request still replaces ctx.transport, and ctx.error is set. Turn it off for site monitoring so a later script can still run.
    • An empty or invalid URL, or an expression that can't be evaluated, also stops the rest of the tap.
  7. On the dashboard.
    • If the data piece has tap actions turned on, the tap runs that list and does not reach components.
    • If a group has tap actions turned on, the tap runs that list and does not reach components inside the group.
    • Otherwise, taps run on components whose Touches is set to Capture. Components set to Pass through do not receive taps.
    • A Timeline, Data table, or HTML component whose content does not fit still scrolls by drag.
    • Configured On long press lists still run outside Edit layout. The item menu (the menu button of a selected item) works only while Edit layout is on for that section.

Variables available during a run

Lua and JavaScript:

Name What it holds
value The current value at this point in the run — updates as each action finishes
raw Fixed for the whole run: the data source's value after its own transformers, as it was when the tap started
transformed Fixed for the whole run: what the data piece or component was showing when the tap started
ctx A shared object for passing information between actions. May include ctx.transport from the bound source (MQTT topic, HTTP request details, WebSocket event, Timer tick, …)
env App-wide text from ENV variables. Read env.my_key. See ENV variables.

Simple expression actions use the same names — value, raw, transformed, ctx, and env — and can also call source_value("Name") or source_raw("Name") to read any other data source by name. On a data piece or component they can read comp / components.

JSONPath in a tap run queries a document with value, raw, transformed, ctx, and env at the top level — for example $.value…, $.ctx…, $.raw…, $.transformed…, $.env.my_key. On a data piece or component it can also read $.comp… and $.components.<id>….

Use raw when you need the data in its original source shape, transformed when you need what the data piece or component was showing at the moment you tapped it (even if a later action changes value), and ctx to carry extra data while value changes.

Passing extra data with ctx

value is the main data for the run. Later actions often replace it — user input, an expression, or an HTTP response written into Pipeline value. Anything you still need after that belongs on ctx.

In Lua or JavaScript:

ctx.note = value
return { command = "set" }

Later actions read ctx.note. An expression uses ctx.note. JSONPath uses $.ctx.note. An HTTP request, MQTT send, WebSocket send, or a destination can insert {{ ctx.note }}.

HTTP request with Apply result → ctx key stores the response body under the name you type and leaves value unchanged. That way the request body can stay in value while the reply sits in ctx.reply.

Don't overwrite error or transport. Put your own extras on other ctx keys; do not mix them into ctx.transport. Extra keys you set during a tap stay for that tap only.

Actions you can add

Grouped in the editor as Data actions and UI actions.

Some lists offer only part of them. On tap hold and On tap release have no actions that show something on screen. A custom screen's or bottom sheet's On open and On close offer Data actions except Apply value and Debounce, plus Set screen result. See On open and On close.

Data actions

Action What it does
Trigger data source(s) Refreshes one or more data sources at the same time. An HTTP source runs its Actions / Transformers pipe. MQTT, WebSocket, and Timer run that source's own transformers. The stored value updates — every data piece using those sources can update. For HTTP, Download in full (on by default) downloads the full response even if it hasn't changed.
Trigger data destination Sends through a reusable destination (HTTP, MQTT publish, or WebSocket). Several data pieces can share it. Text to send and destination fields can include {{ value?.field }}. For HTTP, the response can optionally feed back into the run. For HTTP GET, Download in full (on by default) downloads the full response even if it hasn't changed.
HTTP request Sends an HTTP request from this component only (URL, method, headers, parameters, body, timeout). You can ignore the response, put it into value, or store it under a ctx key. You can insert {{ value?.field }} or {{ ctx.transport… }} from a previous HTTP request in the same list. Leave Body empty to send the current value. Stop pipeline if failed is on unless you turn it off. A failed request then stops later actions. Turn it off for site monitoring. Unchanged data: Reuse (the default) keeps the last response when nothing changed, Always download downloads the full response every time, and Download every N requests does that every N requests.
MQTT send Publishes MQTT from this component only. Pick an existing connection. Topics and Payload can include {{ value?.field }}. Leave Payload empty to send the current value.
WebSocket send Sends a WebSocket message from this component only. Pick an existing connection. Events and Payload can include {{ value?.field }}. Leave Payload empty to send the current value.
Simple expression Evaluates an expression against value, raw, transformed, and ctx, and replaces value with the result. A result that looks like JSON is decoded into an object or array automatically.
JSONPath Pulls data out using a JSONPath query and replaces value with the result. Can take just the first item if the query matches an array.
Lua Runs a Lua script with value, raw, transformed, and ctx available. Whatever it returns replaces value.
JavaScript Runs a JavaScript script with the same names. Lists start at 0. Whatever it returns replaces value.
Apply value Applies a value on the data piece or component — text you set, or the current run's value. Transformers do not run again. On the data piece, inheriting components show that value. The applied value stays until Timeout (ms) or until new data arrives from the data source — whichever comes first. Timeout (ms) of 0 means no timeout (stays until new data). Value can include {{ value?.field }}; leave it empty to use From pipeline.
Stop pipeline Skip every later row without a failure. Conditional run on this row still applies. Same effect as ctx.stopPipeline = true in a script, without writing a script.
Debounce Wait before later rows. A second tap while this list is still running is ignored, so Debounce here only delays the current run.

UI actions

Action What it does
User input: Text Opens a text field; whatever you type replaces value when you confirm. Initial text can include {{ value?.field }}. Visible lines (1–10, default 2) sets how many lines the field shows before it scrolls.
User input: Password Opens a hidden password field with a show/hide button. What you type goes to value (or a ctx key, see Apply result below) when you confirm. It is never prefilled. Presentation is Bottom sheet or Dialog. Prefer a ctx key so a later action can send it without it replacing value.
User input: Select item(s) Shows a list built from the current value (a JSON array of strings, or comma-separated text); your choice replaces value. Selection is One item (value becomes that text) or Multiple items (value becomes a list, which may be empty). Presentation is Bottom sheet or Dialog. Preselect context key (default preselect) names a ctx key whose items start checked — for example set ctx.preselect in an earlier Lua action.
User input: Range Shows a slider for picking a numeric range; value becomes a two-number range. Slider bounds and positions are four numbers [min, max, left, right] and can include {{ value?.field }}. Turn on Decimal to get decimal numbers; off (the default) rounds to whole numbers. Presentation is Bottom sheet or Dialog.
User input: Date Opens a calendar. The day you pick replaces value as text in yyyy-MM-dd form, for example 2026-09-23. Initial date can include {{ value?.field }}; leave it empty to start from the current value, or today. Earliest and Latest limit the calendar (empty means 1900 and 2100).
User input: Time Opens a clock. The time you pick replaces value as HH:mm, for example 14:30. Initial time works like Initial date (empty uses the current value, or now). 24-hour clock is on by default; turn it off for AM and PM. The result is always HH:mm.
Open screen Custom screen opens a named layout from Custom screens (menu → Data → Custom screens). Design Vertical screen and Horizontal screen layouts and pick an Aspect ratio. Set a Default root data source while designing. When you open the screen, you can override that source and pass freeform keys such as room. If a key is not supplied, labels show <room>. The screen can return a value when it closes: Apply result and If closed without a result decide what the next actions get. See Custom screens and Returning a value. Built-in screen jumps to an app screen — Edit data piece (pick which data piece; this one is selected by default), the current section, AI assistant, Data destinations, ENV variables, connections, Settings, and others. Data piece full screen shows the data piece as large as it can fit; pinch to zoom. Close with the header back button. Taps on components still work.
Open bottom sheet Shows a custom bottom sheet over the current screen (menu → Data → Custom bottom sheets). Sheet parameters work like screen parameters. Later actions run when the sheet closes. Apply result and If closed without a result work as on Open screen. See Custom bottom sheets.
Close screen Closes the screen picked in Screen to close: This screen (the screen or bottom sheet the tapped component is on; the default), Screen on top, a Custom screen or Custom bottom sheet you pick, or All screens (back to the main screen). Screens opened over it close too. The main screen never closes. If a screen has unsaved changes, you are asked first. Result (not with All screens) sends a value back to the tap that opened the custom screen or bottom sheet. See Returning a value.
Set screen result Stores a value as the result of the custom screen or bottom sheet this action runs on, without closing it. Whenever that screen closes, the tap that opened it gets the last stored value. Result is a {{ }} template; empty clears the result. Fails outside a custom screen or bottom sheet. See Returning a value.
Open URL Opens an http(s) link. Open with is In-app or System browser. URL can include {{ value?.field }}; leave it empty to use From pipeline.
Wait animation Shows a wait indicator on the component while this tap list is running. It always clears when the list finishes — including Stop pipeline, a cancelled prompt, or a failure. Incoming data from the source does not clear it. Put it first so later actions still run while it is showing. Stop wait animation can hide it earlier.
Stop wait animation Removes a waiting indicator that's currently showing. Use it only when you want to hide progress before the list finishes (for example after Apply value). The list also clears the wait when it ends, so this row is optional.
Show top banner Shows a short message at the top of the screen. Type is Info, Warning, or Error. Text can include {{ value?.field }}. Timeout (ms) is how long it stays (default 1500); 0 keeps it until you close it. A new banner replaces the previous one. Empty text shows nothing. value does not change.
Snack bar Shows a short message at the bottom of the screen. Text can include {{ value?.field }}. Duration (ms) defaults to 4000; 0 keeps it until you close it. A new one replaces the previous one. Empty text shows nothing. value does not change.
Vibrate A short vibration. Strength is light, medium, or heavy. iPad has no vibration, so there the action does nothing.

The five User input actions (Text, Select item(s), Range, Date, Time) have an Apply result setting:

If you cancel the prompt, nothing is written. Open screen (custom screen) and Open bottom sheet have the same setting for the value the screen returns.

Reusable destination vs send from this component only

A data destination is reusable: create it once under Data destinations. Any data piece sends through it with Trigger data destination. Use that when several data pieces should share the same URL, topics, or events.

HTTP request, MQTT send, and WebSocket send live on this component only. Use them when this component has its own URL, topic, or event. MQTT and WebSocket still pick an existing connection; they do not create a destination.

Both paths can insert {{ value?.field }} or {{ env.my_key }} when the tap runs (same names as other tap actions: value, raw, transformed, ctx, env, plus source_value("Name") and source_raw("Name")). Interpolation is not the reason to pick an in-place action — destinations already interpolate on tap.

These three are easy to mix up with an incoming HTTP source:

What it is When to use it What it does to the tap
HTTP data source + Trigger data source(s) Incoming. The source runs its Actions / Transformers pipe on a timer, or when you trigger it. Refresh live data this component (and others on the same source) already show. Updates the stored source value. If this component uses that source, later actions see the new value. ctx.transport.responseTime is that poll, not a tap send. It does not send a one-off POST from the component.
Data destination + Trigger data destination Reusable outgoing (HTTP, MQTT, or WebSocket). You create the destination once. Several data pieces should share one URL, topics, or events. Sends the destination's setup with {{ }} filled in for this tap. Empty Text to send after interpolation uses the tap value. Optional Apply result to pipeline (HTTP only) replaces value with the response body.
HTTP request / MQTT send / WebSocket send Outgoing from this component only. No destination to create. This component has its own URL, topic, or event. HTTP: Apply result Ignore / Pipeline value / ctx key. MQTT and WebSocket: value stays as it was. Empty Body or Payload sends the current value.

A typical tap chain:

Wait animation → Lua, JavaScript, expression, or user input (put extras on ctx if value will change) → HTTP request, MQTT send, WebSocket send, or Trigger data destination → later Lua, JavaScript, or expression reads value and/or ctx → Apply value. The wait clears when the list finishes. Add Stop wait animation only if you want to hide it earlier.

You can mix them. For example Lua or JavaScript keeps a token in ctx.token and builds a body in value; HTTP request uses {{ ctx.token }} in a header; Apply result → ctx key reply; a later script combines ctx.reply with transformed. After a send, Trigger data source(s) can reload inbound state (common after MQTT publish; also after an HTTP poll).

You can insert {{ value?.field }} or {{ env.my_key }} — a simple expression between double braces — in:

If an expression can't be evaluated, the send is not completed and the rest of the tap stops.

Leave the send field empty to send the current value, including a file or image. You can also put only {{ value }} or {{ value.binary }}. Mixing a file or image with other text fails. URLs, headers, topics, and events are text only. For HTTP, set the content type yourself when you send a file or image.

The ctx key name must start with a letter or underscore; use only letters, digits, and underscore, up to 64 characters. Don't use error, transport, or stopPipeline.

A failed MQTT or WebSocket send (missing connection, interpolation error, disconnected/SSE) stops the rest of the tap. The wait indicator still clears when the list finishes. Stop pipeline if failed is on unless you turn it off. A failed request then stops later actions. Turn it off for site monitoring. Lua and JavaScript cannot send HTTP, MQTT, or WebSocket — use HTTP request, MQTT send, WebSocket send, or a destination.

See Data sources, Data destinations, Expressions in editors, and Get started: HTTP POST on tap.

Connect and disconnect on demand

Use Connect and Disconnect when you do not want a link to stay open all the time.

The Keep connected switch stays as you saved it. These actions only hold the live link until you restart the app or flip that switch. While they do, the connection list and HTTP stream rows in the data source list show Connected by action or script or Disconnected by action or script.

This is useful for short-lived links (for example, temporary log stream URLs) where you connect only when needed, then disconnect again.

Tips

See Data destinations (outgoing) for reusable MQTT, WebSocket, and HTTP outbound.

To change how components look on a clock without a tap, use Periodic action pipes on the data piece, a group, or a custom screen — Lua or JavaScript only, not tap actions. Those pipes are not a Timer data source.