All posts
Liferay · 12 min read · Sep 17, 2026

Understanding Fragment Rendering in Liferay

Liferay fragment rendering pipeline

Fragments are the building blocks of modern Liferay page authoring. Instead of dropping heavyweight portlets onto a page, content authors assemble pages from small, reusable fragments - a hero banner, a card grid, a call to action. Each fragment is a bundle of HTML, CSS, and JavaScript with editable regions and configuration. To use them well, you need to understand how a fragment goes from a template to rendered markup on the page.

What a fragment is made of

A fragment is not a compiled component; it is a template. It contains HTML with special markup that defines editable elements, a CSS block scoped to the fragment, an optional JavaScript block, and a configuration schema that exposes options to the author in the editor. When the page is authored, these editable regions are filled with content; when the page renders, the template and the saved content are combined.

  • Editable elements mark regions authors can change - text, images, links, or rich HTML.
  • Configuration fields expose author-facing options like colors, alignment, or layout variants.
  • The CSS is scoped so one fragment's styles do not leak into another.
  • The JavaScript runs on the client after the fragment is placed on the page.

Editable elements bind content to structure

The key idea is the separation between structure and content. The fragment template defines the structure and marks which parts are editable. The author supplies the content into those marked slots. This means the same fragment can appear many times on a site with different text and images while sharing one definition. Change the fragment definition and every instance updates its structure; the per-instance content stays.

html
<div class="promo-card">
  <h3><lfr-editable id="title" type="text">
    Default title
  </lfr-editable></h3>
  <lfr-editable id="image" type="image">
    <img src="placeholder.png" alt="" />
  </lfr-editable>
</div>
Editable regions define where author content is injected into the fragment structure.

How rendering works

At render time, Liferay takes the fragment template, injects the author-provided content into the editable elements, resolves any configuration values, and produces the final HTML. This happens inside the page render phase, which is why fragment rendering must be side-effect free and repeatable, just like portlet rendering.

Content fragments vs mapped content

Fragments can hold their own inline content, or they can be mapped to structured content from the content management system. Mapped fragments pull field values from a web content article or a custom object, so updating the source content updates every page that maps to it. This is the difference between a fragment that owns its text and a fragment that displays someone else's - and it changes where you go to edit it.

ApproachContent lives inBest for
Inline editableThe page instanceOne-off, page-specific content
Mapped to contentA content recordReused, centrally managed content

Caching and performance

Rendered fragment output can be cached, which is what keeps fragment-heavy pages fast. But caching interacts with personalization: a fragment whose output depends on the current user or on permission-filtered content cannot be cached as aggressively as a purely static one. Knowing which of your fragments are personalized is essential before you tune the cache layers.

Common pitfalls

  • Putting logic in fragment JavaScript that assumes a single instance - fragments can appear many times on one page.
  • Unscoped CSS that leaks across fragments because a selector was too broad.
  • Editing inline content when the fragment is actually mapped, so changes appear to have no effect.
  • Expecting personalized fragment output to be cached like static output.

Conclusion

Fragments give Liferay a modern, composable authoring model: reusable templates with clearly marked editable regions, scoped styles, and optional client behavior. Rendering combines the template with author content during the page's render phase, and the same definition can drive many instances. Understand the split between structure and content, and the difference between inline and mapped content, and you can build fragment libraries that authors love and that stay fast under load.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar