Experiences

Creating and Managing Element Variations

Release Feature Liferay DXP 2026.Q3+

An element variation changes one element of a content page for a specific audience, instead of duplicating the whole page into a separate experience. Variations can replace the element’s inner HTML, run JavaScript against the element, or hide the element. Variations are applied in the browser, on top of the experience Liferay DXP renders for the visitor. After you create a variation, you can translate it, set which audience takes precedence when a visitor matches several, and preview the result in a simulation.

Note

Replacing an element’s inner HTML or running JavaScript against it requires custom markup or code. Hiding the element does not.

Prerequisites

Using element variations has these requirements:

A variation can target only an editable fragment element on a content page. Elements that carry no editable ID, including widgets and containers, do not appear in the Page Element picker.

Opening the Element Variations Editor

  1. Open the Site Menu (Site Menu) and go to Site Builder → Pages.

  2. Click Actions for a content page and select Edit.

  3. In the page editor toolbar, click Create Variations next to the experience selector.

    The Create Variations control appears as an icon beside the experience selector in the page editor toolbar.

    The element variations editor opens, with a sidebar for managing variations on the left and a preview of the page on the right. The preview updates as you edit.

Creating an Element Variation

  1. Open the element variations editor for the content page.

  2. Use the Experience selector at the top of the sidebar to choose the experience the variation belongs to.

  3. Click New. When the experience already has variations, click New Variation (New Variation) instead.

  4. Enter a name for the variation.

  5. Select an element in the Page Element picker.

    Each option is labeled with the fragment name and the ID of the editable element inside it, such as Banner (title). Hovering over an option highlights that element in the preview.

    The Page Element picker lists each editable element by fragment name and editable ID, and the hovered option's element is outlined in the preview.

    When the element you want is missing from the list, it most likely does not have the data-lfr-editable-id attribute. For information about making fragment elements editable, see Fragment Specific Tags and Attributes Reference.

  6. Select one or more audiences in the Audience field.

    The field lists the audiences available to the site, except any that another variation already uses for the same page element in the same experience.

  7. (Optional) Toggle Hide Page Element to hide it from the set audiences.

  8. (Optional) Enter custom markup into the HTML field.

    The markup replaces the element’s inner HTML.

  9. (Optional) Enter custom code in the JavaScript field to run it against the element.

    The code runs after the HTML replacement and can use a variable named element, which holds the target element.

    Important

    Once the code has run, its effects stay applied to the preview even as you keep editing. Click Reload to load the preview again and run the current code from a clean page.

  10. Click Save.

    Saving stores the variation on the page’s draft.

  11. Publish the page.

Visitors see element variations only after the page is published. Publishing matches each variation to the experience it belongs to. Because detection runs in the browser after the page loads, visitors may briefly see the default content before a variation is applied.

Translating a Variation

A variation’s HTML and JavaScript values are localizable. Follow these steps to translate them:

  1. Open the element variations editor for the content page.

  2. Use the Experience selector at the top of the sidebar to choose the experience the variation belongs to.

  3. Click Edit on the variation.

  4. Use the language picker in the form header to switch to another language, then edit the fields for that language.

  5. Click Save.

  6. Publish the page.

Liferay DXP serves the value for the page’s language, or the default language’s value when that language’s field is empty.

The Name, Page Element, Audience, Hide Page Element, and Disable Variation fields are not localizable. These settings are shared across languages. For reference, the default language’s value appears beneath each code field.

Setting Audience Priority

A visitor can match several audiences at once, so the browser needs an order to decide which variation to apply. You can set that order in the sidebar, under Audiences Priority.

  1. Open the element variations editor for the content page.

  2. Use the Experience selector at the top of the sidebar to choose the experience whose order you want to set.

  3. Click Edit next to Audiences Priority.

  4. Drag the audiences into the order you want.

    The first audience takes precedence.

    The Audiences Priority modal lists the audiences in priority order, each with a drag handle.

  5. Click Save.

The list shows every audience available to the site, and the order applies to every element of the selected experience. When none is available, the sidebar shows No Audiences Available instead of the list.

How Variations Are Applied

Liferay DXP only evaluates the variations of the experience the visitor is served.

When a visitor matches more than one of an element’s audiences, Liferay DXP only applies the variation of the audience ranked highest in the priority order. The visitor sees one variation per element.

An HTML variation replaces the target element’s inner HTML. It doesn’t add markup around or beside the element. If a variation’s target element is missing from the rendered page, the variation doesn’t apply and its JavaScript doesn’t run.

Simulating Element Variations

Liferay DXP 2026.Q4+

A simulation applies an experience’s enabled variations for a specific audience and previews the page’s draft as a guest sees it, without saving or publishing changes. The Simulation tool only appears in the element variations editor, not the page editor, and requires at least one available audience.

  1. Open the element variations editor for the content page.

  2. Save any open variation form.

    The simulation includes unpublished variations but doesn’t display unsaved edits.

  3. Click Simulation (Simulation) in the element variations editor’s top bar.

    The Page Simulation modal opens full screen, defaulting to the experience selected in the sidebar, the editor’s current language, and the Desktop viewport. Its default audience is the first in the experience’s priority order, or the first in the Audience picker when no order is set. Links in the preview don’t navigate.

  4. Select the experience and audience to simulate in the Experience and Audience pickers.

    The Page Simulation modal shows the selected experience and audience, and its preview shows that audience's variation in place of the heading.

  5. (Optional) Select another language in the language picker.

  6. (Optional) Select a viewport size: Desktop (Desktop), Tablet (Tablet), Landscape Phone (Landscape Phone), or Portrait Phone (Portrait Phone).

  7. (Optional) Click Simulate in a New Tab (Simulate in a New Tab) to open the same experience, audience, and language in a new browser tab.

    The new tab doesn’t use the selected viewport size.

The Simulation panel in the application bar is a different tool that previews a page by segment or experience.

Managing Existing Variations

Use the sidebar of the element variations editor to review and manage the selected experience’s variations, grouped under the page element each one targets. Every entry shows its name, its audiences, and a label for each part it defines: HTML, JavaScript, or Hide Element. A variation that is turned off also shows a Disabled label.

Liferay DXP 2026.Q4+ A variation with no audience shows a Missing Audience label. The variations of a deleted page element are grouped under a Missing Page Element header. See Fixing Incomplete Variations.

Each entry has an Edit quick action, which opens the variation in the form, and an Actions menu where you can Disable or Enable the variation or Delete it.

Searching and Filtering Variations

Liferay DXP 2026.Q4+

Use search and filters to narrow the sidebar’s list of variations.

Follow these steps to search the list:

  1. Open the element variations editor for the content page.

  2. Click Search (Search) in the sidebar toolbar.

  3. Type a search term.

    The list updates as you type, displaying variations in the selected experience whose name, page element, audiences, type labels, or Disabled label match the term. The active term appears in a Search chip.

  4. (Optional) Click Close (Close) to hide the field and keep the term.

To remove the term, click Clear (Clear) in the search field or Clear Search (Clear Search) on the chip.

Follow these steps to filter the list:

  1. Open the element variations editor for the content page.

  2. Click Filter (Filter) in the sidebar toolbar.

  3. Select a category, then check one or more of its values.

    CategoryValues
    AudienceThe audiences available to the site
    IssueMissing Audience, Missing Page Element
    StatusEnabled, Disabled
    TypeHTML, JavaScript, Hide Element
  4. (Optional) Turn on Exclude to match the variations that have none of the checked values.

    The Filter menu shows the Status category with Disabled checked, the Exclude toggle, and the Add Filter button.

  5. Click Add Filter.

With Exclude off, a variation matches a filter if it has any of the checked values. The list only displays variations that match every filter and the active search term. Each category holds one filter, and adding another in the same category replaces it.

Applied filters appear as chips after the result count. Each chip shows its category and values (for example, Status: Disabled). To remove a single filter, click Remove Filter (Remove Filter) on its chip. To remove every filter and the search term, click Clear in the results bar.

When no variation matches, the sidebar shows No Results Found. Click Clear Filters to remove the search term and every filter.

Fixing Incomplete Variations

Liferay DXP 2026.Q4+

A variation is incomplete when its page element is deleted or it has no audience left, either because its audiences were deleted or because their scope no longer includes the site. The variation keeps its HTML, JavaScript, and Hide Page Element setting. An incomplete variation applies to no one until you fix it and publish the page.

If you delete a page element that a variation of the selected experience targets, or a container that holds one, a Delete Referenced Fragments confirmation warns that element variations reference the selection. If you proceed, those variations remain in the sidebar, grouped under Missing Page Element.

If the selected experience contains any incomplete variations, a warning banner appears: There are missing audiences or page elements for some variations. Click Show Variations in the warning to filter the sidebar to variations with a Missing Audience or Missing Page Element issue.

The sidebar shows the warning about missing audiences or page elements, with Show Variations above a variation labeled Missing Audience.

Follow these steps to fix an incomplete variation:

  1. Open the element variations editor for the content page.

  2. Use the Experience selector at the top of the sidebar to choose the experience the variation belongs to.

  3. Click Edit on the variation.

  4. If the variation is under Missing Page Element, select another element in the Page Element picker.

    Changing the page element clears the variation’s assigned audiences.

  5. Select one or more audiences in the required Audience field.

  6. Click Save.

  7. Publish the page.

Feature Availability

FeatureAvailable as BetaAvailable as Release
Element VariationsLiferay DXP 2026.Q3 (LPD-85746)Liferay DXP 2026.Q4 (LPD-85746)
Variation Search and Filters-Liferay DXP 2026.Q4 (LPD-85746)
Incomplete Variation Warnings-Liferay DXP 2026.Q4 (LPD-85746)
Element Variation Simulation-Liferay DXP 2026.Q4 (LPD-85746)