Using Content Management System Assets in Liferay

Beta Feature Liferay DXP 2025.Q4+

Important

Currently, this feature is behind a beta feature flag (LPD-17564) and also depends on a release feature flag (LPD-34594) and a beta feature flag (LPD-11235). Read Feature Flags for details on configuring feature flags and Feature Availability for availability details.

The Liferay Headless Content Management System (CMS) stores, organizes, and manages content and assets across spaces. Its value comes from reusing this content consistently throughout Liferay, instead of duplicating it in each feature.

You can use CMS content in Liferay by mapping CMS fields to fragment elements that support object-based mapping. This mapping displays text, images, and files stored in CMS spaces in pages, fragments, collections, navigation menus, and other supported features, creating a single source of truth for content delivery across the platform.

Note

Some legacy components and selectors still rely on classic assets and are not compatible with CMS objects. See Current Limitations for details.

The example below walks you through creating a space called Marketing and integrating its assets throughout Liferay. Use this procedure to implement your own use case.

Prerequisites

First, Create a space and add your CMS content. Then, connect the space to the site where you want to include this content.

Also, create a display page template and assign it to the CMS asset.

Create a Space

Navigate to the Liferay Headless CMS and create a space named Marketing.
Create basic web content and upload a file in the Marketing space. In this example, use Discover the Possibilities as the web content title and marketing-banner as the image name.
Connect the Marketing space to the site where you want to use it.

When you connect a space to a site, its content structures and assets become available across that site.

Create a Display Page Template

CMS assets use display page templates to define how individual assets are rendered when accessed directly. These templates are required when linking assets from collections or other navigation elements.

Open the Site Menu () and click Design → Page Templates.
Click the Display Page Templates tab and click New.
Enter a Name for your template and select Basic Web Content as the Content Type. Then click Save.
In the Fragments and Widgets sidebar, drag the Heading fragment into the page.
Click the fragment to open its mapping options.
Under Field, select Title.
Drag the Paragraph fragment below the Heading fragment.
Click the fragment to open its mapping options and, under Field, select Content.
Select the Heading fragment and open the Style tab in the right menu (1).
Click Padding Bottom (2) and select Spacer 4 (1.5 rem) (3).
Publish the display page template.
In the Page Templates app, click Actions for the template and select Mark as Default.

The display page template is now associated with basic web content and set as the default display page for that asset.

Using CMS Assets in The Page Builder

Use the Mapping tab in the side panel to surface Liferay Headless CMS content on a page. Some fragments rely on the Direct option for the Source Selection which supports only classic content and Documents and Media items and cannot read CMS assets.

Most fragments use the standard mapping experience. In fragments that include both Direct and Mapping options, choose Mapping to surface CMS assets and their fields in fragment elements.

Fragments With the Liferay Headless CMS Selector

Create a new page or start editing one.
In the Fragments and Widgets sidebar, look for the Heading fragment (1). Drag and drop it into the page (2).
Click the fragment twice to access its mapping options (3 and 4).
Click Add () (3), select Basic Web Contents (CMS) in the left menu, and choose the Discover the Possibilities basic web content.

Tip

All CMS asset types, including those based on custom content structures, appear in this selector. Out-of-the-box CMS assets appear with the (CMS) label.
Under Field (4), select Title.

The Heading fragment now displays the title from the Liferay Headless CMS web content.

Map the fragment to the Liferay Headless CMS asset field you want to display.

Fragments With the Mapping Source Selection

Create a new page or start editing one.
In the Fragments and Widgets sidebar, look for the Image fragment. Drag and drop it into the page under the Heading fragment.
Click the fragment twice to access its mapping options.
Under Source Selection, choose Mapping.
Click Add () → Select Item. Select Basic Documents (CMS) in the left menu and choose the marketing-banner image.
In the Image Source tab, select Preview URL under Field.

That displays the image in the page.

Use the Mapping tab in the side panel to surface CMS content on a page.

Try adding more assets and mapping them to other fragments.

Using CMS Assets in Collections

Use collections to group Liferay Headless CMS assets and reuse them across pages.

Because CMS assets are object-based, publishing a CMS content structure makes its assets available through a corresponding collection provider automatically.

In addition to using collection providers, you can create dynamic and manual collections to further control how CMS assets are grouped and displayed.

Use a Collection Display fragment to surface collection items on a page or select a collection as a mapping source in fragments that support it. See Displaying Collections for details.

Collection Providers

For Liferay Headless CMS assets, collection providers are created automatically when you publish a content structure. Each provider groups all assets created from that structure and becomes available when configuring collections and Collection Display fragments.

This removes the step of defining a collection before displaying CMS assets. Use dynamic or manual collections only when additional filtering, ordering, or item selection is required.

Dynamic Collections

Dynamic collections retrieve items automatically based on the criteria you define. See Displaying Collections and Displaying Object Entries to learn more.

Create a collection and select the Dynamic Collection type.
Under Item Type, select the asset’s content structure (this includes custom structures). Out-of-the-box content structures include Basic Document, Basic Web Content, Blog, and External Video.
Under Scope, click Select → Other Site, Asset Library, or Space….
Open the Spaces tab and select the space that contains your CMS assets.

You can remove scopes by clicking () under Options.
Define your criteria using Filter and Ordering. The collection updates automatically with matching items.

Tip

The Select More Than One option under Multiple Item Types adds multiple asset types to a manual or dynamic collection. See Creating Collections for details.

Manual Collections

For Manual collections, you select which assets to include.

Create a collection and select the Manual Collection type.
Under Item Type, select the asset’s content structure (this includes custom structures). Out-of-the-box content structures include Basic Document, Basic Web Content, Blog, and External Video.
Click Select next to Collection Items and select one of your item types.
In the selector, use the breadcrumbs to navigate to Sites and Libraries.
Open the Spaces tab and select the space that contains your CMS assets.
Select the items to include and click Add.

Now test the collection by adding a Collection Display fragment to a page and mapping it to one of the collections you created.

Using the Collection Display Fragment With Display Pages

You can display a collection of Liferay Headless CMS assets by mapping their fields in a Collection Display fragment and linking each item to its display page. This setup renders a list of assets and routes users to the display page when they select an item.

Create a new page or start editing one.
In the Fragments and Widgets sidebar, look for the Collection Display fragment. Drag and drop it into the page.
Click Select Collection and choose the collection of CMS assets.
Drag a Heading fragment into the top area of the Collection Display.

Note

Before 2025.Q2, you could drop a fragment into any item, and the fragment was replicated across all items. Starting in 2025.Q2, you drop fragments only in the top drop zone, and the system replicates them for the other items. This difference does not affect this example.
Click the first Heading Example to open the mapping options.
Under Field, select Title.
Open the Link tab. Under Field, select the display page template you created in the prerequisites.

Tip

Select the first collection item and add Spacer 3 (1rem) as Padding Bottom to improve the list’s readability.
Click Publish.

Access the page and click a title. The display page template opens and shows the asset title and content.

To improve the overall presentation, customize both the Collection Display fragment on the page and the display page template itself. Use fragments such as buttons, headings, and paragraphs to control how items appear in the list and how individual assets are rendered on their display pages.

Selecting a title from the list opens the asset’s display page.

You can add Liferay Headless CMS assets to navigation menus.

Associate each asset with a display page template so the menu item opens the asset’s display page.
Create a navigation menu.
Click Add and select the asset’s content structure (this includes custom structures). Out-of-the-box content structures include Basic Document, Basic Web Content, Blog, and External Video.
Select the asset to add.

The asset appears as a navigation menu item.

Current Limitations When Using CMS Assets in Liferay

Because Liferay Headless CMS content and files are object-based, using them in Liferay relies on field mapping instead of selecting items directly from the previous-generation item selector. Keep these limitations in mind:

Some fragments do not support Liferay Headless CMS assets.
The Web Content Display and Documents Display fragments work only with classic assets and cannot display CMS assets.

Note

In some fragments, the item selector may display a Spaces tab. This tab is not always connected to Liferay Headless CMS content selection, so CMS items may not appear there.

Not Supported by Design

Image selection in classic CMS components (web content, blogs, knowledge base) works only with classic assets and does not support Liferay Headless CMS objects.