PrimeFaces: Getting Started, Configuration and Themes

PrimeFaces is a component library for Faces: tags in the p: namespace (176 tags in the 16.0.0 tag library, from p:accordionPanel to p:wizard), a theme system, a JavaScript layer built on jQuery that every component talks to, and a set of replacements for parts of the standard machinery. What the 16.0.0 jar registers on its own (read from its META-INF/faces-config.xml and web-fragment.xml) is the reason a page with no explicit setup already behaves differently:

Source: PrimeFaces 16 documentation: Dependencies and PrimeFaces 16.0.0 source: HeadRenderer

The PrimeFaces jar also contains a beans.xml with bean-discovery-mode="all", so a CDI container scans it. On a servlet container that has no Bean Validation or Jakarta Persistence API on the class path, Weld 6.0.4 logged 36 WELD-000119 lines at INFO level ("Not generating any bean definitions from org.primefaces... because of underlying class loading error: Type jakarta.validation... not found"). The application worked; the lines only mean that the optional PrimeFaces features that need those APIs are off (The Dependency and the Optional Libraries).

PrimeFaces is one jar, org.primefaces:primefaces. Its published POM has no compile-scope dependency: mvn dependency:tree on the project below lists the jar and nothing under it. The libraries PrimeFaces can use are declared provided or optional, so each one reaches the WAR only if the application asks for it.

Source: PrimeFaces 16 documentation: Download

The runtime class path of exactly this POM (mvn dependency:copy-dependencies) was primefaces 16.0.0, primefaces-themes 16.0.0, font-awesome 6.7.2, primeflex 4.0.0 and the sanitizer 20260101.1 with its java8-shim and java10-shim jars. Other server-side libraries are needed only by one component each. The versions below are the ones the PrimeFaces documentation says were tested (the 16.0.0 POM leaves the library versions to its parent, so they were not independently checked):

Source: PrimeFaces 16 documentation: Dependencies

The Faces runtime. The PrimeFaces 16 download page lists Jakarta Faces "4.0 - 5.0" as the supported range, and the migration guide says the baseline is now Faces 4.0. The dependencies page still says "2.3, 3.0, 4.0" and "Servlet 3.0+"; that table is stale (flagged). The 16.0.0 jar’s faces-config.xml is a 4.0 document, and the pages of this section ran on Mojarra 4.0.26, Mojarra 4.1.17 and MyFaces 4.1.4. Faces 5.0 is still a milestone (jakarta.faces-api 5.0.0-M9); the download page already lists it, but nothing here was run against it.

No server module. On WildFly, GlassFish, Payara, Open Liberty and TomEE the jar travels inside the WAR like any other dependency. The jar’s web-fragment.xml declares <distributable/>; the deployment and clustering page discusses clustering.

Optional libraries fail loudly. A component whose library is missing does not degrade silently:

Source: PrimeFaces 16 documentation: Hello World

Without owasp-java-html-sanitizer this page, which is the one in the official guide, answered HTTP 500 on Mojarra and on MyFaces: "TextEditor component is marked secure='true' but the HTML Sanitizer was not found on the classpath. Either add the HTML sanitizer to the classpath per the documentation or mark secure='false' if you would like to use the component without the sanitizer." With the dependency from the POM above it rendered on both. The component sanitises the HTML it receives, because rich text typed by a user is untrusted markup. The error message offers secure="false"; do not use it for text that other users will see.

The 16.0.0 jar ships two tag libraries for the same components: primefaces.urn.taglib.xml, namespace primefaces, and primefaces.taglib.xml, namespace http://primefaces.org/ui. Both are discovered automatically and both worked on Mojarra 4.1.17, MyFaces 4.1.4 and Mojarra 4.0.26. The documentation uses the short form, in line with the jakarta.faces.* URNs of Faces 4.0 and later; the long form is what every older tutorial and book shows and keeps working.

Source: PrimeFaces 16 documentation: Hello World

The smallest page that exercises the theme, the icon font, the component styles and the Ajax script is a form with one input and one button:

Source: PrimeFaces 16 documentation: Hello World

The response head of that page, in the order the markup arrives (Mojarra; identical for MyFaces apart from the client ids), was: theme.css from the library primefaces-saga-blue, primeicons/primeicons.css, components.css, jquery/jquery.js, core.js, components.js, jquery/jquery-plugins.js, locales/locale-en.js, then a script that assigns PrimeFaces.settings. The button rendered <button ... class="ui-button ui-widget ui-state-default ui-button-text-icon-left" with an ui-icon pi pi-search span. Nothing in the page, in web.xml or in faces-config.xml asked for any of that.

The h:head of a PrimeFaces application is rendered by org.primefaces.renderkit.HeadRenderer, which replaces the standard renderer of the type jakarta.faces.Head. Its class comment states the intended order: the first facet, the theme style sheet, the PrimeIcons style sheet, the middle facet, the registered resources, the client validation scripts, the locale script, the PrimeFaces.settings script, the initialisation scripts, the content of the h:head element and the last facet. The three facets are PrimeFaces additions to h:head; the standard element knows no facets.

Reading the response shows how that works in practice, because it differs in one detail from the comment. In the output the theme and the icon style sheet come with the registered resources and not before the middle facet, so markup in the middle facet arrives before theme.css. The probe page puts one plain link and one h:outputStylesheet into each facet and into the head:

Source: PrimeFaces 16.0.0 source: HeadRenderer and Jakarta Faces 4.1 VDL: h:outputStylesheet

The style sheets arrived in this order (observed; res-* are the h:outputStylesheet resources, link-* the plain links, all in the library or directory css):

What follows from it:

Source: PrimeFaces 16.0.0 source: HeadRenderer

The consequence for styling is the layout the Bookshelf uses: the application’s own rules go into a plain link in the last facet, and they are written to beat the theme by specificity, not by position:

Source: PrimeFaces 16 documentation: Themes

Source: PrimeFaces 16 documentation: Themes

The selector has two classes, so it beats the theme’s .ui-button rule whatever the order of the files. In headless Chrome the button computed to rgb(111, 66, 193), the accent colour, and not to the Saga Blue rgb(33, 150, 243).

A page without h:head gets nothing. The renderers are attached to the standard tags. A page that uses the plain HTML elements <head> and <body> rendered the PrimeFaces component markup but no link and no script of PrimeFaces on Mojarra and on MyFaces: no theme, no icons, no widgets. Use h:head and h:body in every template and view that holds PrimeFaces components. Faces keeps one renderer per type, so a second library that registers its own jakarta.faces.Head renderer would replace the PrimeFaces one; that case was not tested, so check such a combination in a test.

Moving the scripts to the end of the body. primefaces.MOVE_SCRIPTS_TO_BOTTOM set to true removed every script element from the head and wrote all of them, the PrimeFaces resources, the settings script and the initialisation scripts included, at the end of the body (observed on the hello page: six script elements in the head and two inline widget scripts in the body without the parameter; none in the head and six at the end of the body with it, five resource scripts and one inline script; both widgets of the page were created in all three modes). The value defer additionally gave each resource script a defer="defer" attribute and merged the initialisation scripts into one DOMContentLoaded handler that removes its own element. The page paints before the scripts run, which is the performance advantage the PrimeFaces performance page names (see the PrimeFaces part of the performance page). Test inline scripts of your own that call PrimeFaces or jQuery, because they now run before the library is loaded.

Source: PrimeFaces 16 documentation: Performance

The setup features of this page touch the lifecycle (the six phases) in few places, and knowing which ones explains the theme behaviour above:

Source: PrimeFaces 16.0.0 source: HeadRenderer and Jakarta Faces 4.1 specification, 2.2 Standard Request Processing Lifecycle Phases

PrimeFaces needs no configuration ("configuration by exception"). Everything that can be configured is a context-param in web.xml named primefaces.NAME. The table lists every name the 16.0.0 jar reads (the 22 names of the documentation’s configuration table, plus CACHE_PROVIDER, PUBLIC_CAPTCHA_KEY and PRIVATE_CAPTCHA_KEY that belong to the cache and captcha components, and the three standard parameters it also reads). Parameters are read once when the application starts, with two things to know about expressions: HeadRenderer evaluates the value of THEME as a value expression on every request, and the configuration evaluates the value of CSP as an expression once, while it is built (source). The last column says what was run.

Source: PrimeFaces 16 documentation: Configuration and PrimeFaces 16.0.0 source: PrimeConfiguration

Three standard parameters change PrimeFaces behaviour as well, because it reads them: jakarta.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL (reported to the client as considerEmptyStringNull), jakarta.faces.VALIDATE_EMPTY_FIELDS (auto validates empty fields when Bean Validation is present, reported as validateEmptyFields; on the Tomcat scratch app without Bean Validation it was false) and jakarta.faces.validator.DISABLE_DEFAULT_BEAN_VALIDATOR. They are described on the configuration page of this section (validation parameters).

The documentation table is out of date on one default. CLIENT_SIDE_LOCALISATION is listed with the default false; the PrimeFaces 14 migration guide says it "is now enabled by default" and the 16.0.0 source parses the missing parameter as true (Objects.toString(value, "true")). Observed: without the parameter, a request with Accept-Language: es for an application that supports es wrote locales/locale-es.js; with the explicit value false it wrote no locale script (flagged).

The web.xml the Bookshelf uses for the PrimeFaces-specific part is short. The theme is an expression (Themes), the scripts move to the bottom, partial submit is on, and the CSP is left at its default here because the security page develops it:

Source: PrimeFaces 16 documentation: Configuration

HIDE_RESOURCE_VERSION removes v=16.0.0 from every PrimeFaces resource URL, which keeps the exact library version out of the HTML. The documentation notes that it can be argued whether the version number is a security risk; it also removes the cache buster, so after an upgrade a browser that cached components.js may keep the old file until its cache expires (the resource handling page covers the cache headers: caching headers).

Source: PrimeFaces 16 documentation: Misc

Parameters and filters that are not in the table: the org.primefaces.webapp.filter.CharacterEncodingFilter (UTF-8 unless an encoding init parameter says otherwise) and org.primefaces.webapp.filter.NoCacheFilter (no-cache headers for views) are filters the application maps to the FacesServlet when it wants them (documentation, not run). The request-character-encoding and response-character-encoding elements of a Servlet 6.1 web.xml do the first job without a filter.

A PrimeFaces theme is a resource library named primefaces-<name> that holds one file, theme.css. HeadRenderer takes the value of primefaces.THEME (default saga-blue), evaluates it as a value expression, and writes a link to theme.css in the library primefaces- plus that value. The theme is a style sheet for the ui-* classes that components.css and the renderers use, and it defines the colours, the fonts and the CSS custom properties (--surface-a, --primary-color, --text-color and others) of the page.

PrimeIcons is the icon font of the PrimeTek libraries. It is part of the PrimeFaces jar (the font in five formats under primefaces/vendor/primeicons/fonts and primeicons/primeicons.css), HeadRenderer includes it by default, and the parameter primefaces.PRIME_ICONS set to false removes the style sheet (observed). Icons are CSS classes, pi plus pi-<name>, used on any element or in the icon attribute of components such as p:commandButton:

Source: PrimeFaces 16 documentation: Font Icons

The button with icon="pi pi-search" rendered <span class="ui-button-icon-left ui-icon ui-c pi pi-search"> before its label, and in headless Chrome the ::before content of the icon used the font family primeicons, which the browser reported as loaded. A button without a value and with a title rendered the title as its text (ui-button-icon-only), which gives an icon-only button an accessible name; give every icon-only control a title or an aria-label.

Font Awesome was removed from the PrimeFaces jar in 11.0.0. The documentation says PrimeFaces supports Font Awesome 4.x, 5.x and 6.x or later added by the application as a WebJar. The icons are used the same way (icon="fa-solid fa-book", or a plain <i>) once the style sheet is on the page. The style sheet is the part that needs care, and the check below was run on both implementations:

Source: PrimeFaces 16 documentation: Font Icons

The -jsf variants exist because the font URLs inside the standard style sheet are relative (../webfonts/...), and the URL of a resource served by Faces carries the library as a query parameter (?ln=webjars), which a relative URL cannot express (that is the likely reason; the failure itself, a font in the state error, was observed). The -jsf style sheets replace those URLs with value expressions (the 6.7.2 file contains url("#{resource['webjars:font-awesome/6.7.2/webfonts/fa-brands-400.woff2']}&#")) and Faces evaluates them. The practical rules: use the *-jsf.css file, and before upgrading the WebJar check that it still contains the -jsf files (the 7.3.0 WebJar does not). Pin the version in the library path, as font-awesome/6.7.2/... does; the version is part of the resource name.

Source: PrimeFaces 16 documentation: Font Icons and expressions inside resource files

The PrimeFaces documentation names three ingredients of a responsive page: the page layout (menu, header, content, footer, which is plain HTML and CSS of the application), a grid framework that places the content, and components that adapt to their container. PrimeFaces gives the last two a vocabulary.

PrimeFaces has two places for localised text, the server-side message bundles and the client-side locale scripts, and both are chosen from the Faces locale of the view.

The Faces locale. Which locale PrimeFaces uses is the locale of the view. An application has to declare the locales it supports in faces-config.xml: in the scratch application, without <supported-locale>es</supported-locale> a request with Accept-Language: es was answered with locale:'en_US' in PrimeFaces.settings; with it, the settings carried locale:'es' (see locale selection).

Source: Jakarta EE Tutorial: Configuring Jakarta Faces Applications

Server-side messages. The messages of the components (validation, empty table, file limits) live in org/primefaces/Messages.properties in the jar, with a translation per language: the 16.0.0 jar holds Messages_<language>.properties for Czech, German, Greek, Spanish, Persian, French, Croatian, Hindi, Indonesian (in), Italian, Japanese, Georgian, Korean, Lithuanian, Latvian, Dutch, Norwegian, Polish, Portuguese, Romanian, Russian, Slovak, Swedish, Turkish and Chinese, and an English file. A language that is missing is added, and a shipped message is changed, by putting a file of the same name in WEB-INF/classes (or in an application jar earlier on the class path):

Source: PrimeFaces 16 documentation: Localization

Source: PrimeFaces 16 documentation: Localization

Source: PrimeFaces 16 documentation: Localization

Observed on Mojarra and on MyFaces: with the file, Accept-Language: en gave "No records found." and Accept-Language: es gave "Todavía no hay libros en el catálogo."; without it the shipped Spanish text "No se encontraron registros." appeared. The \uXXXX escapes in the file work with any file encoding.

Client-side texts. The widgets (date picker, filter menus, paginator tips, upload buttons) read their texts and the names of days and months from a JavaScript object, PrimeFaces.locales['<language>'], defined by locales/locale-<language>.js of the library primefaces. The 16.0.0 jar contains 48 of them, with English as the default. With primefaces.CLIENT_SIDE_LOCALISATION enabled, which is the default (The Context Parameters), the head renderer adds the script of the current language, and nothing else is needed:

Source: PrimeFaces 16 documentation: Localization

A page can also load one script by hand, <h:outputScript name="locales/locale-nl.js" library="primefaces"/>, for a language that the Faces locale does not select. A language PrimeFaces does not ship is defined in your own script by assigning a complete object to PrimeFaces.locales['xx']; the documentation lists the keys of the English object (day and month names, firstDayOfWeek, the filter and paginator texts). The client scripts and the server bundles are independent: translate both.

The pieces above make the shell of the PrimeFaces variant of the Bookshelf catalogue (the earlier pages of this section build the plain Faces version). The template carries the head settings, the theme chooser and the message area; a page defines the content. Compared with the plain-Faces template of the templating page (templating) the differences are the p: tags, the PrimeIcons in the header and the last facet:

Source: PrimeFaces 16 documentation: Themes

Source: PrimeFaces 16 documentation: PanelGrid

Source: Jakarta EE Tutorial: Configuring Jakarta Faces Applications

On Mojarra 4.1.17 and MyFaces 4.1.4 the catalogue answered HTTP 200 with four table rows, the theme form switched the theme through the redirect (the theme link changed from saga-blue to arya-blue), and the accent button computed to rgb(111, 66, 193) in headless Chrome. The search field is a plain value read from #{param.q} and only shows the form. The other PrimeFaces pages of this section (PrimeFaces Ajax, forms and validation; PrimeFaces data components; PrimeFaces panels, menus and dialogs; PrimeFaces files, media, charts and drag and drop) replace the table with a lazy model, the ajax="false" button with p:ajax, and add dialogs, menus and uploads to this shell.

The failures of this page are silent (an unstyled page, a font that does not load), so check the result instead of trusting the browser’s first impression. The three requests below are enough; the output is from the Tomcat scratch application with primefaces.THEME set to vela-blue (the ;jsessionid= parts disappear once the client sends the session cookie):

Source: PrimeFaces 16 documentation: Themes

The same three checks belong in an integration test of the application (the testing page builds on them; PrimeFaces Selenium drives the PrimeFaces widgets). In a browser, PrimeFaces.settings and the network tab of the developer tools show the same facts, and document.fonts lists the icon fonts and whether each one is loaded or in error, which is how the Font Awesome table above was produced.

This page stops at the shell of the application. The components and their behaviour are on the pages that follow in this group: PrimeFaces Ajax, forms and validation (p:ajax, process and update with their search expressions (see also PrimeFaces search expressions), partial submit, p:remoteCommand, the input components, client-side validation, p:growl and p:messages); PrimeFaces data components (p:dataTable, LazyDataModel, trees, data export); PrimeFaces panels, menus and dialogs (panels, tab view, menus, p:dialog and the dialog framework); PrimeFaces files, media, charts and drag and drop; PrimeFaces Extensions; OmniFaces; and the page about other component libraries (BootsFaces, Tobago and the discontinued libraries of the older books). Where PrimeFaces runs is covered by Tomcat and Weld, Jakarta EE servers, Spring Boot with JoinFaces and Quarkus. A reader who needs one of those first can start there and come back here for the theme and the configuration.

The setup decisions of this page have security consequences that the later PrimeFaces pages build on:

Source: PrimeFaces 16 documentation: Content Security Policy and PrimeFaces 16 documentation: TextEditor

PrimeFaces is written for both implementations and the pages of this section behaved the same on both, apart from the following (all observed with Mojarra 4.1.17 and MyFaces 4.1.4 on Tomcat 11.0.26 and Weld 6.0.4.Final):

Source: PrimeFaces 16 documentation: Dependencies

PrimeFaces versions move fast and change defaults in every release, so a page or a book is only as good as its PrimeFaces version. The entries below are the ones that matter for this page, from the PrimeFaces migration guides and the 16.0.0 source:

Source: PrimeFaces migration guide 16.0.0 and 15.0.0, 13.0.0 and 10.0.0

The Faces versions matter as well: the jakarta.faces.* namespaces of Faces 4.0 are the ones the PrimeFaces documentation uses for h: and f:, and a PrimeFaces 16 application cannot run on Faces 2.x or 3.x. The documentation tree of the v16.0.0 tag already holds a 17_0_0 folder, a development copy: no PrimeFaces 17 release exists at the time of writing and nothing on this page applies to it. See also the versions and implementations page of this section (Versions and Implementations).

PrimeFaces Cookbook, Second Edition (Çalışkan and Varaksin, Packt, 2015; PrimeFaces 5.1 and 5.2 on JSF 2.2) is the book behind this page: its first chapters cover setup, internationalisation and resource ordering, theming, icons, and panels and layouts. Its approach to organising a PrimeFaces application is still sound; the details are not.

Other books touch this page too. Learning PrimeFaces Extensions Development (Jonna, 2014) sets up a PrimeFaces Extensions 1.2.1 project against PrimeFaces 4.0; the PrimeFaces Extensions page of this section covers the present setup. JSF 2.0 Cookbook (Leonard, 2010) was written for PrimeFaces 2.0 alongside RichFaces and Tomahawk; nothing of its PrimeFaces setup applies. None of the book content is reproduced here.