Flow Screen Lwc Components

Flow Screen LWC Components

Activate this skill when a Screen Flow needs UI behavior that the stock screen components cannot deliver — and you are deciding the shape of a custom Lightning Web Component that will render at runtime inside a screen step. The skill covers the Flow-side contract: which @api properties become Flow inputs and outputs, how FlowAttributeChangeEvent propagates user input back to Flow variables, when to fire FlowNavigationNextEvent, and how the @api validate() hook participates in the Next-button validation cycle. It does NOT cover custom property editors (the design-time admin UX — see flow-custom-property-editors) and is the Flow-domain framing of the LWC implementation deep-dive in lwc/lwc-in-flow-screens.

Before Starting

Gather this context before touching the LWC bundle or the Flow:

• What does the stock component NOT do? Salesforce ships rich screen components — lightning-input, lightning-input-address, lightning-record-form, lightning-record-edit-form, lightning-radio-group, lightning-input-rich-text, plus Reactive Screen Components since Winter '24. Most "I need a custom screen LWC" requests can be solved with stock + a Flow formula. Confirm the gap is real before generating code.
• Is reactivity needed? Reactive Screen Components (Flow API version 59 / Winter '24 +) let one component's output update another component's input on the same screen with no Next click. If the requirement is "field B should update when field A changes," you may not need a custom LWC at all.
• Mobile? Flow Screen LWCs render in the Salesforce mobile app only when <supportedFormFactors> in the targetConfig declares Small. Default is Large only. If the flow runs on mobile, declare both, and test on a real device — not all base components behave identically on mobile.
• Who configures the flow? Admins in Flow Builder will set the @api property values from the property panel. Anything you don't expose in <targetConfig> cannot be set by an admin even if it's @api. Decide which props are admin-tunable vs hardcoded contract.
• What is the validation contract? If the LWC must block the Next button on invalid input, the @api validate() method must return a synchronous { isValid: boolean, errorMessage?: string }. The Flow runtime ignores Promises returned from validate().

Core Concepts

Concept 1 — Targeting lightning__FlowScreen

A component is only available in Flow Builder's screen-component palette if its componentName.js-meta.xml declares <target>lightning__FlowScreen</target>. Without this target, the component does not appear in the palette at all — even if it exists, is deployed, and works perfectly on a Lightning page. The two most common authoring mistakes are: (1) forgetting the target entirely, (2) declaring only lightning__AppPage / lightning__RecordPage and assuming Flow Builder will pick it up.

<targets>
  <target>lightning__FlowScreen</target>
</targets>

If the component should ALSO be usable on a Lightning page, list both targets and gate target-specific behavior with <targetConfig> blocks.

Concept 2 — @api properties become Flow inputs and outputs

Every @api property on the component class becomes a candidate Flow variable. Whether it acts as an input, an output, or both depends on the <targetConfig> declaration:

• Default (input): any @api property listed in <targetConfig> <property> is admin-settable in Flow Builder. The Flow assigns the value into the LWC at render time.
• Output-only: add role="outputOnly" to mark the property as a Flow output. The admin can map it to a Flow variable to receive the value. The LWC must dispatch FlowAttributeChangeEvent to actually push the new value back.
• Input + output: omit role. Admin can both seed the value and map it to a Flow variable that receives updates.

Property type must be one of String, Boolean, Integer, sObject, apex (with extensionName="Namespace.ApexClassName" for Apex-defined types). String is the default if omitted.

Concept 3 — FlowAttributeChangeEvent propagation

The Flow runtime does NOT detect changes to @api properties via setter mutation. To push a new value back to a Flow variable, the LWC must dispatch a FlowAttributeChangeEvent:

import { FlowAttributeChangeEvent } from 'lightning/flowSupport';
// ...
this.dispatchEvent(new FlowAttributeChangeEvent('outputValue', newValue));

The first constructor argument MUST match the @api property's API name exactly (case-sensitive). The second is the new value. Without this dispatch, the Flow variable mapped to the output stays at its initial value, no matter how many times the user types into the field.

Concept 4 — Navigation and validation hooks

Two related hooks let the LWC participate in screen flow execution:

• @api validate() — Flow calls this on every screen LWC when the user clicks Next, Pause, or Finish. The LWC returns { isValid: true } or { isValid: false, errorMessage: 'Reason shown to the user' }. Must be synchronous. If any LWC returns isValid: false, navigation is blocked and the message renders at the top of the screen.
• FlowNavigationNextEvent / FlowNavigationBackEvent / FlowNavigationFinishEvent / FlowNavigationPauseEvent — fire one of these to programmatically advance, retreat, finish, or pause the flow without a user click. Common pattern: a barcode-scanner LWC fires Next automatically after a successful scan. Imported from the same lightning/flowSupport module. The screen must have the matching navigation action available (e.g. Next is unavailable on the last screen — fire Finish instead, or it does nothing).

Common Patterns

Pattern 1 — Output via FlowAttributeChangeEvent

When to use: the user types or selects something inside the LWC and a Flow variable on a downstream element needs the value.

How it works:

1. Declare the property @api outputValue; on the class.
2. Declare it in <targetConfig> with role="outputOnly" (or omit role if it's also an input).
3. On every relevant user event, dispatch new FlowAttributeChangeEvent('outputValue', this.draftValue).
4. The admin maps {!outputValue} to a Flow variable in Flow Builder.

Why not the alternative: mutating this.outputValue = newValue without dispatching the event leaves the Flow variable stale. This is the #1 cause of "my flow always sees the empty value."

Pattern 2 — Programmatic Next on validation success

When to use: scanner / kiosk / single-question screens where you want the flow to advance the moment a valid value is captured, with no Next button click.

How it works:

1. Capture the user input (scan, key press, OAuth callback).
2. Validate inline. On failure, render an inline error and do nothing.
3. On success, dispatch new FlowAttributeChangeEvent(...) for every output property.
4. Then dispatch new FlowNavigationNextEvent().

The order matters. If you fire Next before the attribute-change events propagate, the next screen may render before the Flow runtime sees the new variable values. Dispatch attribute changes first, await Promise.resolve() (microtask flush), then fire Next if you've seen ordering issues.

Why not the alternative: auto-firing Next without validate() participation means a manual Next click later in the flow could replay this screen's bad state. Always also implement @api validate() so the same gating runs on a manual click.

Pattern 3 — Reactive component pair

When to use: the value of one custom LWC's output should update another custom LWC's input on the same screen, with no Next click.

How it works:

1. Both LWCs target lightning__FlowScreen.
2. The "source" LWC dispatches FlowAttributeChangeEvent for its output property.
3. The admin in Flow Builder wires the source's output → a Flow variable → the target LWC's input. This is just the normal Flow Builder property panel mapping — there is no LWC-to-LWC direct binding.
4. The Flow's API version must be 59.0 or higher. Older flows ignore reactive updates.
5. The target LWC sees the new input as a property assignment; if it needs to react, implement a setter or renderedCallback that responds to the change.

Why not the alternative: older aura:attribute-style cross-component messaging does not exist for Flow screens. Do not try to use pubsub, lightning/messageService, or DOM querying to share state across screen LWCs — Flow's variable model is the contract.

Decision Guidance

Use this table to decide whether a screen requirement justifies a custom LWC at all, and which Flow-side mechanic fits.

Recommended Workflow

1. Confirm the gap. Search the stock screen-component palette and reactive-formula docs. If a stock combination satisfies the requirement, do not author an LWC. Cite the gap in the design notes.
2. Decide the I/O contract. List every @api property and label it input, output, or both. Pick the type for each (String, Boolean, Integer, sObject, apex). Write the contract down before writing code.
3. Author the meta.xml first. Declare <target>lightning__FlowScreen</target>, then <targetConfig targets="lightning__FlowScreen"> with one <property> per admin-configurable @api field. Mark outputs role="outputOnly". Set <supportedFormFactors> if mobile is in scope.
4. Implement the LWC class. Match every @api property to a <property> in meta.xml. Wire user-input handlers to dispatch FlowAttributeChangeEvent for every output. Implement @api validate() synchronously and return the documented shape.
5. Wire navigation events only if needed. Most components do not need to fire FlowNavigationNextEvent — let the user click Next. Auto-advance is justified only for scanner / kiosk / single-question patterns.
6. Test in Flow Builder + at runtime. Add the component to a throwaway Screen Flow. Verify (a) the component appears in the palette, (b) configurable properties show in the property panel with correct types, (c) outputs propagate to Flow variables, (d) validate() blocks Next when expected, (e) reactivity works on Flow API 59+.
7. Document the contract in the LWC's README or skill-local examples. Future admins will reuse this component without reading the source — make the input/output table discoverable.

Review Checklist

• lightning__FlowScreen target is declared in meta.xml.
• Every @api property exposed to admins has a matching <property> entry in <targetConfig> with the correct type.
• Every output property has role="outputOnly" AND a FlowAttributeChangeEvent dispatch on user input.
• @api validate() is synchronous (no async, no await, no Promise return) and returns { isValid, errorMessage? }.
• Navigation events (Next/Back/Finish/Pause) are only fired when the screen actually has that action available.
• Reactive cross-component dependencies are documented and the consuming Flow is at API version 59+.
• Mobile support is either explicit (<supportedFormFactors> includes Small and tested on device) or explicitly out of scope.
• No usage of pubsub, lightning/messageService, or DOM cross-querying to share state with other screen LWCs.
• No lwc/wire data fetch is gated by validate() — validate() cannot wait on a Promise.

Salesforce-Specific Gotchas

1. Missing lightning__FlowScreen target → invisible in Flow Builder. The component deploys cleanly, shows up under Setup → Lightning Components, but the screen-component palette in Flow Builder never lists it. There is no error message — the absence is silent. Always grep the meta.xml for the target string before debugging anything else.
2. @api validate() must be synchronous. If you write async validate() or return a Promise, Flow ignores the return value entirely and treats the screen as valid. Users sail past invalid input. Detect this by reading the method signature: any async keyword or .then( inside the function is a defect.
3. Reactive screen components require Flow API version 59+. Building a perfectly correct LWC pair and dropping them into a Flow created on an older API version produces a screen where outputs propagate only on Next, not in real time. The Flow's API version is set at flow creation; admins frequently clone old flows and never update it.
4. FlowNavigationFinishEvent from a non-final screen ends the flow abruptly. The runtime treats Finish as terminal regardless of where it fires. If the LWC is on screen 2 of 5, firing Finish skips screens 3-5 entirely, including any post-screen DML actions. Use FlowNavigationNextEvent unless the LWC actually knows it is on the last screen.
5. role="outputOnly" does not auto-emit value changes. Declaring the role in meta.xml makes Flow Builder show the property in the output mapping panel, but the runtime still requires an explicit FlowAttributeChangeEvent dispatch. Outputs that "don't update" almost always have the role set correctly but no event dispatch in the JS.
6. FlowAttributeChangeEvent attribute name is case-sensitive. Dispatching new FlowAttributeChangeEvent('OutputValue', v) for an @api outputValue property silently fails — the Flow runtime cannot match the names. Always copy the property name exactly.
7. @api properties are typed by what JS assigns at runtime, not what meta.xml says. If meta.xml declares type="Integer" but the LWC dispatches a string, Flow may coerce or warn at design time — but at runtime, downstream Flow elements may receive the wrong type. Validate types in the dispatch site.
8. Importing from lightning/uiRecordApi or other base modules inside validate() does not work. validate() is called synchronously during Next-click handling; any async data fetch initiated there returns a Promise the runtime ignores. Pre-fetch in connectedCallback or via @wire, store on the instance, and validate against the cached value.

Output Artifacts

Related Skills

• skills/flow/flow-screen-flows — design framing for Screen Flow as a whole, before deciding to drop in a custom LWC.
• skills/flow/flow-reactive-screen-components — reactivity rules for stock components; check this before authoring a custom LWC for a reactivity-only requirement.
• skills/flow/flow-screen-input-validation-patterns — stock validation rule patterns; preferred when the validation can be expressed declaratively.
• skills/flow/flow-screen-flow-accessibility — accessibility requirements for screen flows, applies equally to custom LWC screens.
• skills/flow/flow-custom-property-editors — the OTHER LWC-in-flow scenario: design-time configuration UX, not runtime rendering.
• skills/lwc/lwc-in-flow-screens — the LWC-domain implementation deep-dive (the component-author's view of the same contract).
• skills/lwc/lwc-component-skeleton (template templates/lwc/component-skeleton/) — the canonical LWC bundle starting point.
• skills/lwc/lwc-flow-properties — typed input/output declaration patterns in <targetConfig>.

Official Sources Used

• Lightning Web Components Dev Guide — Build Components for Flow Screens: https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-builder-screen.html
• Lightning Web Components Dev Guide — lightning/flowSupport Module: https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-flow-support.html
• Lightning Web Components Dev Guide — Configure a Component for Flow Screens (targetConfig): https://developer.salesforce.com/docs/platform/lwc/guide/reference-targets.html
• Salesforce Help — Reactive Screen Components: https://help.salesforce.com/s/articleView?id=sf.flow_concepts_screen_reactive.htm
• Winter '24 Release Notes — Reactive Screens: https://help.salesforce.com/s/articleView?id=release-notes.rn_automate_flow_builder_reactive_screens.htm
• Lightning Web Components Dev Guide — Custom Property Editors (for distinguishing scope): https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-custom-property-editor.html