A flow is an ordered list of screens. Users move forward and back through that list with actions. This page covers linear navigation, then the realistic options for making a flow respond to state: conditional content (well supported) versus conditional paths (limited in the editor today).
How the editor builds a flow
The editor has no node-graph canvas. You build a flow as an ordered list of screens in the Layers panel (“Add Screen” appends a new screen), and the connections between screens are maintained automatically to match that order. Navigation is driven by actions, not by drawing arrows.
Linear navigation
Four actions move the user around:
| Action | What it does |
|---|
Go to Next Screen (goNext) | Advance to the next screen in order. Stays correct as you reorder screens. |
Go Back (goBack) | Return to the previous screen. |
Navigate to Screen (navigate) | Jump to one specific screen you pick. |
Close Flow (closeFlow) | End and dismiss the flow. |
Conditional content vs conditional paths
There are two different things people mean by “branching”:
- Show different content on the same screen depending on state. This is fully supported with dynamic values and is the recommended approach.
- Send the user to a different screen depending on state. This is limited in the editor today. Read the next section before you design around it.
When you can express a difference as “different text, color, or visibility,” prefer a single screen with dynamic values. It is simpler to build, simpler to preview, and avoids duplicate screens.
Conditional paths today
A Navigate to Screen action picks one fixed screen from a dropdown. Its target is not a dynamic value, so you cannot make a single navigate action point at different screens based on a variable.
The flow schema does define branching node kinds (condition, assign, abTest) that the SDK evaluates at runtime, but the editor has no UI to create them. There is no palette that places a condition or A/B node onto the flow; the only node you can add is a screen.
The experimental-nodes flag (NEXT_PUBLIC_FLOWPILOT_EXPERIMENTAL_NODES) only un-gates creation of api, event, and subflow nodes in the underlying store. It does not add any palette for condition, assign, or abTest, and even when on there is still no UI that places a non-screen node. In practice, nothing branch-related becomes placeable from the editor. Verify against lib/editor/feature-flags.ts and components/editor/LayersPanelNew.tsx if this changes.
- For A/B testing different flows, use a placement-level experiment. That is the supported way to split traffic between variants. Do not try to build A/B logic inside a flow.
- For in-flow conditionals, use dynamic values to change what a screen shows.
- The
api, event, and subflow node kinds are not supported by the SDK at all (they are dropped). Do not build with them. They appear only in advanced schema discussions; see the flow schema reference.
Example
A quiz result on one screen. Suppose a quiz sets a score Number variable. Instead of routing to three different result screens, use a single results screen and make its properties dynamic:
- Heading text, driven by
score:
- when
score at least 80 -> Great job!
- when
score at least 50 -> Nice work
- else ->
Keep practicing
- Heading Color, with the same thresholds (green / amber / red).
Because the first matching rule wins, the 80 rule comes before the 50 rule. The screen now “branches” its content from one place, and a single Close Flow (or Go to Next Screen) button ends the quiz.
If you truly need to send users to genuinely different next steps, model that as separate flows behind an experiment rather than an in-flow branch.
Common mistakes
- Trying to A/B test inside a flow. In-flow A/B branching is not the right tool. Use a placement experiment.
- Leaving a screen with no way forward. Every screen except the last needs a forward action (Go to Next Screen or Navigate to Screen), and the flow needs a Close Flow somewhere to end.
- Building with unsupported nodes.
api, event, and subflow are dropped by the SDK. Do not rely on them.
- Expecting a conditional navigate target. A navigate action points at one fixed screen. Use dynamic values for conditional content, or experiments for variant flows.
Related pages
