LWC Custom Property Editor for Flow Explained

Updated 9 min read
LWC Custom Property Editor featured image showing a configuration panel for a Flow element

An LWC Custom Property Editor replaces the plain list of inputs an admin sees when they configure your component in Flow Builder. Instead of six text boxes with API names, the admin gets a designed panel with pickers, toggles and live validation.

This matters once a component has more than a couple of settings. A list of raw inputs invites mistakes, and every mistake surfaces as a broken screen in production rather than an error at build time.

LWC Custom Property Editor diagram showing input variables and change events

Caption: Flow Builder owns the saved values, and your editor only reports changes.

What Is an LWC Custom Property Editor

An LWC Custom Property Editor is a separate Lightning Web Component that Flow Builder renders inside the element configuration panel. It is not the component the user sees at runtime. You build two bundles, one for the screen and one for its editor.

BundleWhere it runsWho sees it
Screen componentIn the running FlowThe end user
Property editorIn Flow BuilderThe admin building the Flow

The editor receives the current settings in a public property called inputVariables, and it reports every change by firing an event. It never writes the values itself.

The Metadata

An LWC Custom Property Editor declares a different target from a normal component. Flow screen components themselves are covered in the post on LWC in Flows.

<targets>
  <target>lightning__FlowScreenPropertyEditor</target>
</targets>

The screen component then points at the editor from its own meta file.

<targetConfig targets="lightning__FlowScreen"
  configurationEditor="c-course-picker-cpe">
  <property name="courseId" type="String" label="Course" />
  <property name="showFee" type="Boolean" label="Show fee" />
</targetConfig>

Note the kebab case name in configurationEditor. A camel case name here is one of the most common reasons the editor never appears.

How the Value Contract Works

The LWC Custom Property Editor reads an array and fires events. That is the whole contract.

import { LightningElement, api } from 'lwc';

export default class CoursePickerCpe extends LightningElement {
  @api inputVariables = [];

  get courseId() {
    const found = this.inputVariables.find(v => v.name === 'courseId');
    return found ? found.value : undefined;
  }

  handleCourseChange(event) {
    this.report('courseId', event.detail.value, 'String');
  }

  report(name, value, type) {
    this.dispatchEvent(
      new CustomEvent('configuration_editor_input_value_changed', {
        bubbles: true,
        composed: true,
        cancelable: false,
        detail: { name, newValue: value, newValueDataType: type }
      })
    );
  }
}

Three details decide whether the LWC Custom Property Editor works at all. If custom events are new ground, see custom events. The event name is fixed and spelled exactly as above. The event must set bubbles and composed to true so it escapes the shadow boundary. And the detail keys are name, newValue and newValueDataType, not the names you might expect.

Data type stringUse it for
StringText, ids, picklist values
NumberNumeric settings
BooleanCheckboxes and toggles
referenceA Flow variable the admin picked

That reference type is how an admin passes a Flow variable instead of a fixed value. Send the variable name as the value and reference as the type.

Why an LWC Custom Property Editor Matters

BenefitWhat it gives the admin
Real pickersA course record picker instead of a pasted id
Validation at build timeAn error in the builder, not in production
Grouped settingsRelated options side by side
Helpful labelsPlain words instead of API names
Fewer support callsThe wrong value becomes hard to enter

The validation point is the strongest one. A default editor accepts anything typed into a text box. An LWC Custom Property Editor can refuse to let the Flow be saved until the settings make sense.

Blocking a Save

Flow Builder asks the LWC Custom Property Editor to validate before it saves. Expose a public validate method that returns an array of errors.

@api validate() {
  const errors = [];
  if (!this.courseId) {
    errors.push({ key: 'courseId', errorString: 'Pick a course' });
  }
  return errors;
}

An empty array means the settings are valid. Anything in the array shows in the builder and stops the save. This one method removes a whole class of production problem.

Default Editor vs LWC Custom Property Editor

LWC Custom Property Editor and default editor comparison diagram

Caption: The build cost is real, so keep the default editor for simple components.

Component settingsReasonable choice
One or two text valuesDefault editor
A record id the admin must pasteCustom editor
Settings that depend on each otherCustom editor
A JSON string the admin has to writeCustom editor
A single checkboxDefault editor
Six or more related optionsCustom editor

The JSON row is the clearest case. If your component takes a JSON configuration string, an admin will eventually get a comma wrong and the screen will fail at runtime. An editor that builds the JSON for them makes that impossible.

A Real LWC Custom Property Editor Example

An LWC Custom Property Editor changed how our own admins work. Bright Path Tutors has a Flow screen component that shows course details and an optional fee. The settings are a course id, a flag for the fee, and a level filter.

The first version used the default editor. Admins pasted record ids by hand, and two Flows broke because an id came from a sandbox.

We built an editor with a record picker, a toggle and a level dropdown.

SettingDefault editorCustom editor
CoursePasted 18 character idlightning-record-picker
Show feeText box with true or falselightning-input toggle
LevelFree textDropdown from the picklist
Bad value caughtAt runtimeBefore the Flow saves

The record picker was the piece that paid for the work. It searches live records, so a sandbox id can no longer reach a production Flow. If record pickers are new to you, the post on base components lists what each one does.

Reading Flow Variables and Context

Flow Builder can also hand the LWC Custom Property Editor a list of the variables available in that Flow, through a property named builderContext.

@api builderContext;

get textVariables() {
  const vars = this.builderContext ? this.builderContext.variables : [];
  return vars
    .filter(v => v.dataType === 'String')
    .map(v => ({ label: v.name, value: v.name }));
}

That gives you a dropdown of the Flow’s own text variables, which is how a proper merge field picker is built. Send the chosen name with the reference data type so Flow resolves it at runtime.

Limits and Things to Watch

  • An LWC Custom Property Editor runs only in Flow Builder, so it needs its own target in the meta file
  • The event name and detail keys are fixed and case sensitive
  • The editor cannot read Salesforce data through a wire adapter in every release, so test your data calls early
  • Values arrive as strings, so convert numbers and booleans yourself
  • The editor is not rendered at runtime, so never put business logic in it
  • A screen component can have only one configuration editor

Common Mistakes with an LWC Custom Property Editor

MistakeWhat you seeFix
Camel case configurationEditor nameThe editor never appearsUse the kebab case name
Missing bubbles and composedThe value never savesSet both to true on the event
Wrong detail keysSilent no changeUse name, newValue and newValueDataType
Mutating inputVariablesA read only errorTreat it as read only and fire events
No validate methodBad settings reach productionAdd validate and return errors
Business logic in the editorIt never runs for usersKeep logic in the screen component
Wrong data type stringThe value saves but is unusableMatch the type to the property

Best Practices for an LWC Custom Property Editor

  • Read values through getters rather than copying them into fields
  • Fire one event per property that changed, not one for everything
  • Always add a validate method, even for a single required setting
  • Use record pickers and dropdowns in place of any text box holding an id
  • Convert numbers and booleans explicitly, since values arrive as strings
  • Name the editor bundle after the screen component with a clear suffix
  • Write a Jest test for the event detail, since the keys are easy to get wrong

Most Asked LWC Custom Property Editor Interview Questions

Q1: What is a custom property editor?

A Lightning Web Component that replaces the default configuration panel an admin sees in Flow Builder.

Q2: Does the end user ever see it?

No. It runs only inside Flow Builder, while the screen component runs for the user.

Q3: Which target does the editor declare?

The lightning__FlowScreenPropertyEditor target in its meta file.

Q4: How does the screen component point at its editor?

With the configurationEditor attribute on its target config, using the kebab case component name.

Q5: Why does a camel case name fail?

The attribute expects the kebab case form, so a camel case value simply never matches.

Q6: How does the editor receive current values?

Through a public inputVariables property, which is an array of objects with name, value and type.

Q7: Can you change inputVariables directly?

No. It is read only, so you report changes with an event instead.

Q8: What is the event name?

configuration_editor_input_value_changed, spelled exactly that way.

Q9: Which event options are required?

Both bubbles and composed must be true so the event escapes the shadow boundary.

Q10: What keys go in the event detail?

The name, newValue and newValueDataType keys.

Q11: Which data type strings are used?

String, Number, Boolean and reference, among others.

Q12: What does the reference type mean?

The value names a Flow variable rather than holding a fixed value, so Flow resolves it at runtime.

Q13: How do you stop a Flow saving with bad settings?

Expose a public validate method and return an array of error objects.

Q14: What does validate return when all is well?

An empty array.

Q15: What is in each error object?

A key naming the property and an errorString holding the message.

Q16: What is builderContext for?

It gives the editor the Flow’s own variables and elements, so you can build a merge field picker.

Q17: Why is a record picker better than a text box for an id?

It searches live records, so an id from another org cannot be pasted in.

Q18: Does the LWC Custom Property Editor run business logic?

No. It only collects configuration, so logic belongs in the screen component or Apex.

Q19: Can one screen component have two editors?

No. Only one configuration editor is allowed per component.

Q20: Scenario: the editor renders but values never save. What is the first thing to check?

The event, specifically the bubbles and composed options and the detail key names.

Q21: Scenario: a number setting saves but arrives as text. Why?

The data type string was wrong, or the value was never converted before it was reported.

Q22: Scenario: the panel is blank in Flow Builder. What is wrong?

Usually the target is missing from the editor meta file, or the configurationEditor name is wrong.

Q23: Do App Builder components use the same pattern?

App Builder has its own property editor support, and the ideas carry over even though the targets differ.

Q24: How do you test the editor?

With Jest, by setting inputVariables and asserting the detail of the event your handler fires.

Q25: When is the default editor good enough?

When there are one or two plain values and nothing depends on anything else.

Q26: What is the strongest argument for building one?

Validation before save, since it turns a production failure into a build time message.

Q27: Can the editor query Salesforce data?

Treat data calls as something to test per release, since behaviour inside the builder has changed over time.

Q28: What is the one habit that avoids most of the pain?

Keep the editor thin, read values through getters, and report every change with a correctly shaped event.

Official Resources

What Is Next

Next, read TypeScript in LWC Setup and Type Safety Explained.