preview_component_selector#

The preview_component_selector field is used at the component level to tell Page Builder how to identify the main rendered DOM node for the component. When PageBuilder Inspector is activated visual highlighting for the component will be available when the component is selected.

This field is optional but highly recommended for enabling accurate preview targeting in Page Builder and ease of use.

`preview_component_selector` Definition#

This field belongs in the top level of your flex.json file:

{
  "code": "my-hero-component",
  "name": "Hero Block",
  "type": "component",
  "version": "1.0.0",
  "preview_component_selector": ".hero-block",
  "resourcegroup_code": "my-hero",
  "instance_template": "templates/instance.mvt",
  "properties": [ ... ]
}

In this example, the component’s main wrapper element must include the class .hero-block in the output of the instance template.

Supported Tokens#

You can use tokens to dynamically generate the selector based on runtime context:

Token	Description
`%component_code%`	Replaced with the Flex Component’s `code`
`%sequence_code%`	Replaced with the enclosing sequence’s code
`%sequence_item_code%`	Replaced with the sequence item’s code
`%element_code%`	Replaced with the enclosing sequence element
`%element_item_code%`	Replaced with the sequence element’s item code

These tokens allow selectors to work in repeatable and dynamic layouts like carousels or tabbed regions.

Supported Fields#

Field	Type	Required	Description
`preview_component_selector`	string	No	CSS selector used to identify the root DOM element for preview interaction

This should match exactly the output structure rendered by the instance_template.

Page Builder uses this selector to attach live preview effects (e.g., highlight, update, show/hide).
It works in coordination with preview_property_selector (used on individual properties).
The DOM node you target should wrap the visual portion of the component.

Template Usage#

If your flex.json uses:

"preview_component_selector": ".hero-block"

Your instance_template should output:

<div class="hero-block">
  <h1>...</h1>
</div>

If using tokens:

"preview_component_selector": ".component-%component_code%"

Then render:

<div class="component-mmx-hero">
  ...
</div>

Assuming code: "mmx-hero".

Best Practices#

Always use a unique, scoping-friendly class on your root element.
Match the selector exactly — Page Builder relies on it.
Avoid generic selectors like .container or div.
Use %component_code% to future-proof reusable components.
Pair with preview_property_selector for enhanced live editing.

preview_component_selector#