General Guidelines for Creating a Custom Property Editor

These recommendations can help you avoid common mistakes and deliver a consistent end-user experience when you create a custom property editor.

Don't use the property editor to validate user input. The property editor is intended to affect only the user interface in Experience Builder. Make sure that the property editor always sends the user-input value without changing or processing it. The property sheet validates the input value by ensuring that the property value is valid according to the property's type schema. If the property sheet finds any validation errors, it injects those errors into the property editor via the errors property.

This code sample shows what not to do. In the sample, the code violates this guideline by performing a validation check on the value entered by the user and setting its own error message. The code also bypasses firing the valuechange event when this special validation condition is met.

Don't create flyouts, popouts, or window overlays (also known as modals). These user experience patterns can interrupt the Experience Builder user's editing experience.

Don't use CSS to define the absolute position of an element. This pattern doesn't always behave as expected and can cause elements to be misaligned. (See MDN Web Docs: position for more information.)

Don't set CSS width properties to determine the width of your property editor. Setting width properties affects the size of the property panel in Experience Builder and can cause problems with user experience.

Don't fire the valuechange event too often. A canvas refresh is triggered whenever the property sheet handles the valuechange event fired from a property editor. Too many refreshes of the canvas per second hinders Experience Builder performance. For example, when you bind valuechange to events such as keydown or mousemove for an input, the canvas refreshes multiple times per second. We recommend binding valuechange to a committal event, such as blur, instead.

This example shows what not to do. Here, the valuechange event fires on every keypress of an input. An Experience Builder user who types rapidly can unknowingly trigger dozens of canvas refreshes and slow down the editing experience of this component.