Screen Flows

Use this skill when the Flow is interactive and the quality of the user journey matters as much as the automation logic. Screen flows succeed when they guide the user through a deliberate sequence, validate at the right moments, and commit data only where the consequences are clear. They become fragile when navigation, validation, and side effects are all mixed together casually.

The three most common screen-flow design failures: (1) DML happens on screen 2 of 6, so clicking Back from screen 5 leaves half-committed data, (2) custom LWC screen component's validation doesn't integrate with the Flow runtime, so users hit Next through invalid inputs, (3) screen count grows from 3 to 11 over iterative "just one more screen" additions until the flow is unusable on mobile. This skill exists to prevent those.

Before Starting

Check for salesforce-context.md in the project root. If present, read it first.

Gather if not available:

• How many decision points and data-entry steps are truly necessary for the user to complete the task?
• Which fields can rely on standard screen components, and which require a custom LWC because the runtime UX truly differs?
• At what point should the flow create or update data, and what should happen if the user clicks Back, Cancel, or Next with invalid inputs?
• Who is the target user (internal employee on desktop, field agent on mobile, Experience Cloud customer)?
• Will this flow be embedded as a Quick Action, Lightning Record Page component, utility bar flow, or standalone URL?

Core Concepts

Screen flows are interviews, not pages. That means the experience is stateful, sequential, and sensitive to where the design commits work. A strong screen flow keeps the user focused on entering or confirming information. A weak one starts performing irreversible actions too early or makes validation unpredictable between screens.

Commit Timing Is A UX Decision

If the flow creates or updates records before the user reaches a natural confirmation point, Back and Cancel become much harder to reason about. In many cases, the best pattern is to gather inputs first, show a summary or final confirmation, and only then perform the final DML.

Standard Components Are Usually Better Defaults

Flow screen components cover many common needs without custom code. Reach for a custom LWC screen component only when the interaction model, validation behavior, or rendering requirement truly exceeds what standard screen elements provide.

Standard screen components handle:

• Text, Number, Date, DateTime, Email, URL, Phone inputs
• Picklist, Multi-select Picklist, Radio Buttons, Checkbox, Checkbox Group
• Lookup (single- and multi-select)
• Dependent Picklists (controlling/dependent relationships)
• Rich Text display
• File Upload
• Data Table (including editable)
• Address compound input

Multi-select choice components output a string, not a collection. Checkbox Group and Multi-Select Picklist let a user pick more than one value (unlike single-select Picklist and Radio Buttons), but they store every checked selection in a single semicolon-delimited text string, not a native Flow collection variable. Feeding that output straight into a Loop, a Get Records filter, or a Transform element fails — those elements expect structured (collection) data, so convert the string to a collection first. Checkbox Group, Choice Lookup, and Multi-Select Picklist are all explicitly incompatible with the Transform element for this reason, and all three require the Lightning runtime (they do not render on the Classic Flow runtime). On Lightning runtime version 58 and earlier these components also keep no built-in memory of their values: selections are dropped on Back navigation, pause/resume, or an input-validation error unless an attribute is configured to retain them. From Winter '24 (GA; Beta in Spring '23), Checkbox Group is a reactive source — other components on the same screen can react to its selections without a Next click — and since Spring '23 its choices can be backed by a multi-select picklist field with record-type awareness.

A custom LWC screen component is warranted when you need: cascading reactive UI between multiple fields on the same screen, real-time external-system validation, a rendering that truly isn't expressible with standard components (drag-and-drop, inline image annotation, etc.), or when a reusable LWC you already own must be surfaced.

Custom Screen Components Need A Validation Contract

A custom LWC used in Flow has to cooperate with Flow runtime validation intentionally. That means implementing the right methods and making sure internal validation, externally supplied error messages, and displayed errors stay consistent with how the user moves between screens.

Required contract for Flow-compatible LWCs:

• @api validate() method returning { isValid: boolean, errorMessage?: string }.
• @api-exposed properties aligning with Flow variable types.
• FlowAttributeChangeEvent dispatched when internal state changes affect Flow variables.
• FlowNavigationNextEvent (optional) when the component wants to force advancement.

Missing any of these creates the "Next clicks past invalid data" class of bugs.

Navigation Should Feel Predictable

The number of screens, presence of a Back path, and clarity of button labels all shape the experience. If a flow has too many screens or too much hidden branching, users stop understanding where they are in the process.

Heuristic: < 4 screens feels like a form; 4–7 screens feels like a wizard; > 7 screens feels like a maze. If the flow needs more than 7 screens, reconsider: is this one task or two? Can some screens be combined? Does a custom LWC display replace a multi-screen sequence?

Common Patterns

Pattern 1: Gather, Review, Then Commit

When to use: Any flow where the user enters meaningful data or confirms a business transaction.

Structure:

Screen 1: Collect inputs (required fields, defaults where safe)
Screen 2: Collect additional inputs (conditional on Screen 1's answers)
Screen 3: Review screen — read-only display of ALL values the user entered + "Confirm" button
[On Confirm click → Create Records / Update Records / Invoke Apex action]
Screen 4: Confirmation — "Done. Record created: <link>"

Why not the alternative: Early record mutation makes cancellation and back-navigation behavior harder to trust; the user reasonably expects Back and Cancel to undo their changes.

Pattern 2: Standard Components First, Custom Component Only For Real Gaps

When to use: Most inputs are standard, but one part of the experience needs custom UX or validation.

Structure:

Screen 1: Standard components (Name, Status, Date)
Screen 2: STANDARD fields + ONE custom LWC component for the exceptional interaction
          (e.g., a reactive product configurator that depends on Screen-1's selections)
Screen 3: Review + commit (Pattern 1 from here)

Why not the alternative: Rebuilding entire screens as custom LWCs raises maintenance cost, bypasses Flow Builder's accessibility features, and makes the flow harder for admins to adjust.

Pattern 3: Bounded Screen Count With Clear Branching

When to use: A process needs several decisions but should still feel guided.

Structure: Every Decision element leads to at most 2 "branch endings" (screens specific to that path). Avoid branches that loop back to common screens — causes confusing Back behavior. Use Is First Screen / Is Last Screen pattern via dynamic component visibility to signal progress.

Pattern 4: Modal Flow (Quick Action) vs Full-Page Flow

Screen flows behave differently by surface:

The commit-timing rules change per surface: modal Cancel is a strong "undo" signal; full-page Cancel is a "leave the page" signal. Align UX to surface.

Decision Guidance

Review Checklist

• Each screen has one clear purpose and does not overload the user.
• Validation timing is predictable for both standard and custom components.
• Data commit points are intentional and not placed too early.
• Back, Next, Cancel, and Finish behavior all make sense to a real user.
• Custom screen components implement the @api validate() contract.
• Mobile or smaller-screen behavior was considered when layout matters.
• Screen count is within the "form / wizard / maze" heuristic range.
• Fault handling exists on the commit step (Pattern A from flow/fault-handling).

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Common Patterns above; choose the surface deliberately
4. Validate — run the skill's checker script and verify against the Review Checklist above
5. Document — record any deviations from standard patterns and update the template if needed

Salesforce-Specific Gotchas

1. A screen flow is not automatically reversible — once DML has happened, Back and Cancel cannot behave like true undo.
2. Custom screen components need to cooperate with Flow validation — they do not get correct validation behavior for free; missing @api validate() lets users click Next past errors.
3. Too many screens feel like poor information architecture, not better guidance — sequence alone does not improve UX.
4. Standard components are easier to support than fully custom screen UIs — custom screens should be the exception.
5. Finish button does NOT always go where admin expects — screen flows finish at an implicit redirect; use {!$Flow.CurrentRecord} or explicit redirect to control.
6. Mobile behavior differs from desktop — custom LWCs may render differently; some standard components (Data Table edit mode) have reduced mobile support.
7. Quick Action modal has a narrower width than standalone — layouts that work in full-page break in the modal.
8. Back-button is disabled by default on some screen types — explicitly enable if the UX needs it; don't rely on browser back.
9. Screen flows in Experience Cloud inherit the site's profile, not the invoking user's — sharing implications differ (see flow/flow-for-experience-cloud).
10. Lookup component defaults to the first match on typeahead — users sometimes pick the wrong record; include a disambiguator (e.g. show Account Name next to Contact Name).
11. Checkbox Group / Multi-Select Picklist output is a semicolon-delimited string, not a collection — wiring it straight into a Loop or Get Records filter silently breaks; convert to a collection first. Checkbox Group, Choice Lookup, and Multi-Select Picklist are also incompatible with the Transform element.
12. Checkbox Group requires the Lightning runtime and, on runtime v58 and earlier, has no memory — selections vanish on Back, pause/resume, or a validation error unless an attribute is configured to retain them. From Winter '24 it can serve as a reactive source for other same-screen components.

Proactive Triggers

Surface these WITHOUT being asked:

• DML on screen 2 of 6 without a staging-model justification → Flag as High. Almost always wrong; move commit to post-review.
• Custom LWC screen component with no @api validate() method → Flag as Critical. Users can Next past invalid data.
• Screen flow with > 7 screens → Flag as Medium. Reassess info architecture.
• Quick Action modal flow with > 4 screens → Flag as High. Modal is the wrong surface for that many screens.
• Full-page flow with Cancel behavior not explicitly specified → Flag as Medium. Users guess — ambiguity invites support tickets.
• Custom LWC used where standard components would suffice → Flag as Low. Maintenance-cost observation, not a bug.
• Back button disabled on a wizard-style flow → Flag as Medium. Users want to go back; disabling surprises them.
• Screen flow embedded in Experience Cloud without guest-access review → Flag as Critical. Route to flow/flow-for-experience-cloud.
• Checkbox Group / Multi-Select Picklist output wired directly into a Loop, Get Records filter, or Transform element → Flag as High. The output is a semicolon-delimited string, not a collection; convert it first.

Output Artifacts

Related Skills

• flow/flow-for-experience-cloud — use when the screen flow is being embedded for external users or guest audiences.
• flow/fault-handling — use when the harder problem is failure behavior after the user submits.
• flow/record-triggered-flow-patterns — when the screen flow's commit triggers a record-triggered flow downstream.
• lwc/custom-property-editor-for-flow — when the question is about Flow Builder design-time configuration rather than runtime screen UX.
• lwc/lwc-in-flow-screens — companion LWC-side skill for building the custom components.