JSF Facelets Templates and Composite Components Explained
Build JSF Facelets templates with ui:composition and ui:insert, include fragments with ui:include and write reusable composite components with cc:interface.

Facelets is the view technology of Jakarta Faces. A Faces page is not JSP, and it is not plain HTML: it is an XHTML file that Facelets parses into a tree of components. Facelets also provides the two ways to avoid repeating yourself in a Faces application, templates and composite components. They look similar and solve different problems, and mixing them up leads to either copy-pasted markup or to components that are really page layouts. This post explains both, builds a template and a composite component, and covers the build-time versus render-time difference that causes most Facelets surprises. It uses Jakarta Faces 4 on Jakarta EE 10 or 11.
A template
A template is a page that defines the common frame and marks the places that vary with ui:insert.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:h="jakarta.faces.html"
xmlns:ui="jakarta.faces.facelets">
<h:head>
<title><ui:insert name="title">Shop</ui:insert></title>
<h:outputStylesheet library="css" name="site.css"/>
</h:head>
<h:body>
<header><ui:include src="/WEB-INF/includes/nav.xhtml"/></header>
<main>
<ui:insert name="content">No content</ui:insert>
</main>
<footer>© Example Ltd</footer>
</h:body>
</html>The text inside ui:insert is the default shown when a page does not fill the slot. The template lives under WEB-INF, so a browser cannot request it directly, which is the safe place for anything that is not a page.
A client page
A page that uses the template applies it with ui:composition and fills the slots with ui:define:
<ui:composition xmlns="http://www.w3.org/1999/xhtml"
xmlns:h="jakarta.faces.html"
xmlns:ui="jakarta.faces.facelets"
template="/WEB-INF/templates/layout.xhtml">
<ui:define name="title">Orders</ui:define>
<ui:define name="content">
<h:dataTable value="#{orderBean.orders}" var="o">
<h:column><f:facet name="header">Number</f:facet>#{o.number}</h:column>
</h:dataTable>
</ui:define>
</ui:composition>Everything outside ui:define inside a ui:composition is ignored, so the page contains only its own parts. The same page can be requested as orders.xhtml, and the browser receives the template frame with the content in place. Templates can nest: a section template uses the site template and defines its own slots. The expression language that links the page to beans is covered in expression language and value binding.
Fragments with parameters
ui:include pulls in a file, and ui:param passes values to it:
<ui:include src="/WEB-INF/includes/address.xhtml">
<ui:param name="address" value="#{order.shippingAddress}"/>
<ui:param name="heading" value="Ship to"/>
</ui:include>Inside address.xhtml, #{address.street} and #{heading} refer to the parameters. This is fine for fragments that are markup with a couple of values. The limits are the point where a composite component becomes better: an include has no declared interface, so a reader of the include cannot see which parameters it needs, there is no type, no default and no documentation, and a missing parameter evaluates to empty text without an error.
A composite component
A composite component is a reusable component written as XHTML. It lives in a resource library, and its path becomes its tag.
<ui:component xmlns="http://www.w3.org/1999/xhtml"
xmlns:h="jakarta.faces.html"
xmlns:ui="jakarta.faces.facelets"
xmlns:cc="jakarta.faces.composite">
<cc:interface>
<cc:attribute name="value" required="true"/>
<cc:attribute name="label" default="Address"/>
<cc:attribute name="required" type="java.lang.Boolean" default="false"/>
</cc:interface>
<cc:implementation>
<h:outputLabel for="street" value="#{cc.attrs.label}"/>
<h:inputText id="street" value="#{cc.attrs.value.street}" required="#{cc.attrs.required}"/>
<h:inputText id="city" value="#{cc.attrs.value.city}" required="#{cc.attrs.required}"/>
</cc:implementation>
</ui:component>Use it in a page by declaring a namespace for the library. In Faces 4 the namespace is jakarta.faces.composite/ followed by the library name; before Faces 4 it was http://xmlns.jcp.org/jsf/composite/ followed by the name.
<html xmlns:ui2="jakarta.faces.composite/ui">
<ui2:addressField value="#{order.shippingAddress}" label="Ship to" required="true"/>
</html>The folder resources/ui becomes the library ui, the file addressField.xhtml becomes the tag addressField. The cc:interface declares the contract: attributes with types, defaults and required flags, and it can expose parts of the implementation, such as an input's value for validators, with cc:editableValueHolder and cc:actionSource. The cc:implementation is the markup, and #{cc.attrs.name} reads an attribute. Because the interface is declared, tools can validate usage and a missing required attribute fails clearly. A composite component is the right choice for a reusable piece of UI with inputs and behaviour, such as an address block, a date range or a labelled field with its error message. It behaves like a component in the tree: it has its own naming container, so ids inside it are scoped, and it can be updated by AJAX with f:ajax render. The look can be built on a component library, see PrimeFaces.
Build time versus render time
This is the part that explains most puzzling behaviour. Facelets tags come in two kinds, and they run at different moments.
Build-time tags are handled when the component tree is built, the first time the view is requested: ui:include, ui:composition, ui:define, c:if and c:forEach from JSTL core. They decide the shape of the tree. Render-time components are the Faces components themselves, such as h:inputText and h:dataTable, and the attribute rendered, which are evaluated every time the view is rendered.
The consequence: <c:if test="#{user.admin}"> is evaluated once when the tree is built, and the result is baked into the tree, so if user.admin changes later in the same view, the markup does not change. rendered="#{user.admin}" is evaluated on every render, so it follows the value. Use rendered for conditions that can change during the life of the view and c:if only for conditions fixed when the view is created, such as a configuration flag. The same applies to c:forEach against ui:repeat: the first builds components for each item at tree-build time, the second renders the same component repeatedly at render time. For lists that change, use ui:repeat or a data table. Bean scope interacts with this, as in bean scopes, where the lifecycle phases are laid out.
Choosing between the two
A template defines the structure of whole pages: the frame, the slots, the shared head. A composite component defines a unit of interface used inside pages, with a declared contract. If you find yourself passing five ui:param values to an include, write a composite component. If you find yourself writing a composite component that contains a header, a menu and a content slot, you wanted a template. Plain includes are for static fragments, such as a navigation list.
Resource libraries and caching
A composite component's file lives in a resource library, and Faces serves the other resources in the library (CSS, scripts, images) through the resource handler with a version in the URL, so browsers cache them correctly. Put the component's styles in the same library and reference them with h:outputStylesheet library="ui", so the component and its look travel together. In development, Facelets checks files for changes on every request (jakarta.faces.FACELETS_REFRESH_PERIOD set to a low value); in production, set the period to -1 so templates are compiled once and never re-read, which is a large difference in request time on pages with many includes.
Debugging a template
Mistakes in templates tend to appear as a page that renders without the part you expected. The project stage Development makes Faces print the component tree problems and shows the ui:debug panel when you add <ui:debug hotkey="x"/> to a page and press Ctrl-Shift-x, listing the component tree and the scoped variables. A ui:define whose name does not match any ui:insert is silently ignored, so a typo in a slot name produces an empty region and no error. Keep slot names in one place, and a short comment in the template listing them.
Where this does not apply
Component libraries ship their own layouts and tags, and for a large application you may use a PrimeFaces layout and write composites only for domain-specific pieces. Facelets also supports custom tag libraries and Java-backed components, which are heavier and rarely needed. The tags are specified in the Jakarta Faces 4.0 specification, and live examples of the component set are in the PrimeFaces showcase.


