SfSkills Domains Docs GitHub

Home / flow / flow-custom-property-editors

flow-custom-property-editors

Decide whether a Flow screen component or invocable action needs a Custom Property Editor at all, and if it does, what the design-time contract owes the admin: which configuration fields are genuinely unmanageable in the default property pane, how generic sObject type mapping gets declared, and how the design-time editor is kept from drifting away from the runtime component it configures.

Open the skill folder on GitHub

Use this skill when the Flow-side question is "should this component or action have a custom configuration experience in Flow Builder, and if so, what should that builder contract look like?" The purpose is to keep Flow Builder configuration clear for admins while preventing the runtime component contract and the design-time editor contract from drifting apart.

Custom Property Editors (CPEs) are the FLOW BUILDER admin UX for configuring an LWC screen component or invocable action. They are not the runtime UI the end user sees — that's a separate LWC. This distinction matters because admins frequently conflate the two, build a runtime component, and then wonder why the Flow Builder configuration experience is awkward. The CPE is the DESIGN-TIME surface; the LWC is the RUN-TIME surface; they share a data model but are separate components with separate lifecycles.

Before Starting

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

Gather if not available:

Core Concepts

This Is A Builder Concern First

Flow custom property editors exist to improve Flow Builder configuration, NOT runtime execution. The first design question is whether admins truly need a guided design-time UI. If the builder experience is simple enough with standard property inputs, a custom editor is unnecessary complexity. CPEs add:

All of this is worth it when the default property pane is genuinely confusing or error-prone. Not worth it when the component has 2 scalar inputs.

The Flow Contract Must Stay Stable

The editor reads and writes the component's configuration through builder-side contracts such as inputVariables, builderContext, and related metadata. Those contracts are Flow-facing APIs. If the runtime component changes names or assumptions without the editor changing too, the Flow setup becomes misleading or broken.

ContractWhat it providesWhen to use
@api inputVariablesArray of existing input values the admin has setAlways — read current state
@api builderContextFlow metadata: variables, constants, formulas in the FlowWhen editor needs to pick from Flow resources
@api automaticOutputVariablesOutput variables the component will produceRarely; mostly for complex invocable editors
@api genericTypeMappingsType mappings for generic sObject / collection inputsWhen the runtime component is generic (typed at Flow design time)
FlowAttributeChangeEventFire when admin changes a field — writes back to FlowEvery change must dispatch this; otherwise changes don't persist

Generic And Context-Aware Editors Need Strong Boundaries

Some editors only manage a few scalar values. Others need object metadata, generic type mapping, or awareness of what resources already exist in the Flow. The more context-aware the editor becomes, the more important it is to keep the builder logic narrowly focused and well documented.

Rule of thumb: the editor's job is "translate admin intent into inputVariables that the runtime component will consume correctly." If the editor is doing other things (side-effectful CRUD, complex business logic), it has escaped its lane.

Metadata Registration Is Part Of The Design

The .js-meta.xml configuration is not boilerplate. The configurationEditor registration, targets, property definitions, and any generic type declarations are part of the Flow extensibility design. A polished editor component is useless if Flow Builder is not wired to it correctly.

<!-- Runtime component's .js-meta.xml -->
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>60.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__FlowScreen</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__FlowScreen" configurationEditor="c-myEditorLwc">
            <property name="recordId" type="String" />
            <property name="fieldApiName" type="String" />
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

The configurationEditor attribute points to the EDITOR LWC (which is a separate bundle). If that attribute is missing or wrong, Flow Builder falls back to the default property pane — and the custom editor never fires.

Common Patterns

Pattern 1: Guided Scalar Editor

When to use: The component exposes a small set of values that need better labels, help text, or validation than the default Flow property pane provides.

Structure: Register a custom editor, read inputVariables, write changes via FlowAttributeChangeEvent, keep the UI limited to design-time concerns (labels, help text, validation rules).

Pattern 2: Context-Aware Resource Picker

When to use: Admins must choose Flow resources, objects, or generic types that depend on builder context.

Structure: Use @api builderContext to read the Flow's existing variables/constants. Filter them by type. Present as a picklist. Write the admin's selection back as a variable reference (e.g., {!MyVar}) — not a raw value.

Pattern 3: Generic Component Type Mapper

When to use: Runtime component accepts generic @api sobject input (e.g. "works on any object") — admin needs to specify which object type at Flow design time.

Structure: Use @api genericTypeMappings in the editor to propagate the selected type to the runtime component's metadata. Validate that the chosen object is accessible + has the required fields.

Pattern 4: Runtime And Editor Contract Pairing

When to use: The same component is expected to be reused in many Flows and needs durable design-time governance.

Structure: Define a clear input model once (e.g. MyComponentConfig DTO), mirror it intentionally in the editor, and treat metadata + editor UI + runtime expectations as one contract. Version the contract together; never change only one side.

Decision Guidance

SituationRecommended ApproachReason
Simple scalar inputs onlyDefault Flow property paneLowest maintenance cost
Admins need guided setup, validation, or dynamic choicesCustom Property Editor (Pattern 1)Better design-time UX
Flow config depends on object/resource contextBuilder-context-aware editor (Pattern 2)Default pane too weak
Runtime component is generic over sObjectType mapper editor (Pattern 3)Required for generic Flow input
Cross-Flow reuse at scaleContract pairing (Pattern 4) with versioningReuse + governance
The real problem is runtime LWC implementationUse lwc/custom-property-editor-for-flowBuilder and runtime are separate concerns

Review Checklist

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

  1. Gather context — confirm the org edition, runtime component shape, admin UX needs
  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; keep editor scope narrow
  4. Validate — run the skill's checker script and verify against the Review Checklist above
  5. Document — record any deviations from standard patterns; pair the editor + runtime contracts explicitly

Salesforce-Specific Gotchas

  1. A working runtime component can still have a broken Flow Builder experience — design-time and runtime are separate surfaces with separate failure modes.
  2. configurationEditor registration is part of the contract — if metadata is wrong, Flow Builder never invokes the editor no matter how good the LWC code is.
  3. Builder context is not a runtime API — editors that assume runtime behavior instead of Flow Builder behavior become fragile fast.
  4. Visual polish is irrelevant if the editor never emits FlowAttributeChangeEvent — Flow Builder configuration stays stale until the event contract is correct.
  5. CPEs can't access user data at design time — they run in the admin's builder context, not in a user context. Don't assume record access; use builderContext for Flow metadata only.
  6. CPE bugs can corrupt Flow metadata — an editor that writes malformed values can leave the Flow in an unrecoverable state. Test destructive edits in sandbox.
  7. Flow Builder caches CPE LWC — changes to the editor may not appear without a hard refresh. Document this for admin testers.
  8. Namespaced CPE components in packages are opaque to consumers — if the package is managed, consumers can't customize the editor. Plan the stable contract carefully.
  9. Lightning Web Security affects CPE DOM access — modern LWS enforces stricter shadow-DOM boundaries; older CPEs may break silently after LWS rollout.
  10. The Property Editor view does not auto-resize — complex editors may overflow the default Flow Builder panel. Use slds-scrollable_y and test at multiple screen sizes.

Proactive Triggers

Surface these WITHOUT being asked:

Output Artifacts

ArtifactDescription
Flow extensibility reviewFindings on when a custom editor is justified and how the builder contract should work
Property-editor contractMapping of Flow inputs, builder-side validation, runtime fields
Metadata registration checklistRequired .js-meta.xml + eventing decisions for the Flow-facing surface
Versioning planHow CPE + runtime pair evolves across releases

Package files