> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getflowpilot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactions and actions

> An interaction connects a component event, like a tap, to a list of actions that run in order.

An **interaction** wires a component event (a tap, or the screen appearing) to a list of **actions**. When the event fires, the actions run top to bottom. Actions are how a flow does things: change a variable, move to the next screen, fire an analytics event, play a haptic, close the flow.

<Note>
  The full interaction editor (multiple actions, multiple events, delays) is an **Advanced mode** surface. In [Simple mode](/editor/editing-modes) an interactive block gets one **"When tapped"** action from a curated verb list (Continue, Go back, Go to screen, Open link, Finish flow), plus a "Haptic on tap" toggle and, on single-choice questions, an "Auto-advance" toggle. See [Block controllers](/editor/block-controllers#when-tapped).
</Note>

## Where interactions live

Select a component, open the **Logic** tab in the [properties panel](/editor/properties), and find the **Interactions** section. For a [custom component](/editor/custom-components) the same section is labelled **Tap Behavior**.

The section has:

* A **When** picker that chooses which event the action list responds to.
* A **Disabled** toggle (which can itself be a [dynamic value](/editor/dynamic-values)).
* The **action list**, with an **Add** button.

## Events

For a built-in component, the **When** picker offers two events:

| Picker label  | Event      | When it fires                  |
| ------------- | ---------- | ------------------------------ |
| **On Tap**    | `onPress`  | The user taps the component    |
| **On Appear** | `onAppear` | The screen shows the component |

**On Appear** runs once when the screen appears. Pair it with delayed actions to step a value over time (for example, walk a bound number from 0 up to a target).

The schema also defines `onChange`, `onFocus`, and `onBlur`, but you do not author those here. They are handled implicitly. A text input, for example, writes its value into a bound variable on its own.

For a [custom component](/editor/custom-components), the picker is **When Event** and lists the events that component declares in its definition (its `customEventKey` values), not the built-in events.

## The action list

Click **Add** to append an action. Each action row has:

* A **type** dropdown (what the action does).
* Config fields for that type.
* A **Delay** field in milliseconds.

Actions run in the order they appear in the list. **Delay** is an absolute offset from the moment the event fired, not a wait after the previous action. A list of `[Set Variable @ 0ms, Set Variable @ 1000ms]` changes the variable now and again one second later, independent of each other. Leave Delay empty or `0` to run immediately.

## Action types

The **type** dropdown offers these actions:

| Type (label)                | What it does                                 | Key fields                         |
| --------------------------- | -------------------------------------------- | ---------------------------------- |
| **Navigate to Screen**      | Jump to a specific screen                    | the target screen                  |
| **Go to Next Screen**       | Advance along the flow order                 | none                               |
| **Go Back**                 | Return to the previous screen                | none                               |
| **Close Flow**              | Dismiss the whole flow                       | none                               |
| **Set Variable**            | Apply an operation to a variable             | variable, operation, value         |
| **Open URL**                | Open a link                                  | the URL                            |
| **Haptic Feedback**         | Play device haptic                           | intensity (Light / Medium / Heavy) |
| **Trigger Event**           | Send an analytics event                      | event name                         |
| **Trigger Animation**       | Run a reactive animation step on a component | target component, step             |
| **Trigger Particle Effect** | Play a particle burst                        | effect and options                 |

A few notes on individual actions:

* **Navigate to Screen** picks one fixed screen from a dropdown. The target is not itself a dynamic value. For state-driven paths, see [Navigation and branching](/editor/navigation-and-branching).
* **Go to Next Screen** follows the flow's screen order, so it stays correct as you add and reorder screens.
* **Trigger Event** is FlowPilot's `trackEvent` action. The field is labelled **Event Name** and becomes the event's key in your analytics. See [Analytics (iOS)](/ios-sdk/analytics) for how events reach your tools.
* **Trigger Animation** targets a component and one of its reactive animation steps. See [Animations](/editor/animations).
* **Trigger Particle Effect** plays an effect overlay. See [Particles](/editor/particles).

### Set Variable operations

**Set Variable** is the main way to change state. Only [Flow State](/editor/variables) variables appear in its picker (App Parameters are read-only). The operations offered depend on the variable's type:

| Variable type | Operations                                                                         |
| ------------- | ---------------------------------------------------------------------------------- |
| **Boolean**   | Set ON, Set OFF, Toggle                                                            |
| **Number**    | Set to value, Increment by, Decrement by, Multiply by, Divide by, Reset to initial |
| **String**    | Set to value, Append, Prepend, Clear                                               |
| **List**      | Add item, Remove item, Toggle item, Clear list, Set list                           |

A **Quick Actions** strip offers one-tap presets for the most common operations (Toggle on/off, Next step, Toggle selection, Clear selections, and so on) based on the variable's type.

### Two more actions in the schema

Two action kinds exist in the flow schema but are not in the type dropdown:

* **`assign`** evaluates an expression into a variable. The editor uses it under the hood (for example, a custom component's output payload is compiled into `assign`-style writes), so you do not add it by hand.
* **`custom`** carries an `actionKey` and `params` for native handling. Native handler support differs by SDK: the **Expo** SDK exposes a public `registerCustomAction(key, handler)` so a `custom` action can run native code on device (see [Custom actions (Expo)](/expo-sdk/custom-components#custom-actions)). The **iOS** SDK has no public registration API for `custom` actions yet, so on iOS model native behavior as a [custom component (iOS)](/ios-sdk/custom-components) that emits an event instead. See the [actions reference](/reference/actions-reference).

## Example

**A Continue button.** On a "Continue" button, set **When** to **On Tap** and add, in order:

1. **Set Variable** -> `step` -> **Increment by** -> `1`
2. **Trigger Event** -> Event Name `continue_tapped`
3. **Go to Next Screen**

The variable updates, the event is recorded, then the flow advances. Order matters: if **Go to Next Screen** came first, the screen would change before the variable was set.

**A staggered reveal.** On a screen's component, set **When** to **On Appear** and add two **Set Variable** actions on the same bound value with different **Delay**s (for example `0ms` and `400ms`). Because each delay is measured from when the screen appeared, the value steps from one state to the next on its own.

## Required questions and inputs

In [Simple mode](/editor/editing-modes), choice and input [block controllers](/editor/block-controllers) have a **Required** toggle. It gates a target (usually the Continue button, or a button in a persistent [zone](/editor/zones)) so it stays disabled until the question is answered or the field is filled, then enables. You pick the target in the **Disables** dropdown.

Under the hood this compiles to a conditional **`disabled`** value on the target that watches the block's variable for emptiness, so it works the same on device as any other [dynamic value](/editor/dynamic-values). The gated value is managed by the editor: in Advanced it shows read-only ("Set by a Required question on this screen"). To change it, toggle Required off on the question or input block. This is the curated, one-toggle version of the **Gated Continue** pattern you can also build by hand in Advanced (see [Blocks](/editor/blocks)).

## Preview is not the runtime

The editor's [preview](/editor/preview-and-live-mirror) is a close approximation, not the device runtime.

* **In edit mode** (not previewing), only visual and sensory actions fire: **Trigger Animation**, **Trigger Particle Effect**, and **Haptic Feedback**. Navigation, Set Variable, Close Flow, Open URL, Trigger Event, and custom actions do not run, so a stray click on a wired button will not switch screens or change state while you author.
* **In preview mode**, state and navigation actions run against preview-only state. Navigation, variable changes, and the like update the preview and show a toast; they never touch real flow data. Open URL shows a confirmation rather than leaving the editor.

Use a real build to confirm end-to-end behavior.

## Common mistakes

* **Wrong action order.** Putting `Go to Next Screen` before a `Set Variable` means the variable never gets set on the screen the user just left. List state changes before navigation.
* **Navigating to a deleted screen.** A **Navigate to Screen** action that points at a screen you later delete has no valid target. Re-point it.
* **Expecting `custom` to work on device.** Custom actions have no public native handler on iOS yet. Treat them as not-yet-functional on device.
* **Authoring `onChange` by hand.** Input changes are wired implicitly through variable binding, not through the action list.

## Related pages

* [Variables](/editor/variables)
* [Dynamic values](/editor/dynamic-values)
* [Navigation and branching](/editor/navigation-and-branching)
* [Animations](/editor/animations)
* [Particles](/editor/particles)
* [Actions reference](/reference/actions-reference)