PrimeFaces is a popular UI component library for JavaServer Faces that helps you build rich, interactive web interfaces with less manual JavaScript and CSS. It provides ready-to-use components such as data tables, dialogs, calendars, menus, charts, buttons, and form controls that integrate naturally with JSF managed beans and Jakarta EE applications.
This quick start focuses on getting a basic PrimeFaces application running from the ground up. You will see the required Java and Jakarta EE setup, how to create a simple JSF project, how to add PrimeFaces dependencies, and how to build a small page using PrimeFaces components.
As an Amazon Associate I earn from qualifying purchases.
By the end, you should have a working foundation that you can expand with validation, navigation, templates, database access, and more advanced PrimeFaces features as your application grows.
Recommended Free Tools
What PrimeFaces Is and When to Use It
PrimeFaces is a component library for JavaServer Faces, commonly known as JSF. It gives you a large collection of ready-made UI components that can be used in server-side Java web applications. Instead of writing every input field, data table, dialog, menu, calendar, or chart by hand, you add PrimeFaces tags to a JSF page and connect them to Java backing beans. PrimeFaces then handles much of the HTML rendering, styling, Ajax behavior, validation integration, and component state management.
A typical PrimeFaces page uses XHTML with JSF tag libraries and PrimeFaces components. For example, a form may contain a text input, a command button, and a messages area. When the user clicks the button, PrimeFaces can submit the form with Ajax, call a method in a managed bean, update only part of the page, and display validation messages without a full browser refresh. This style fits well with applications where the server owns the UI flow and business actions are implemented in Java.
Where PrimeFaces fits in a Java web stack
PrimeFaces is not a full application server, database layer, or replacement for Jakarta EE. It sits on top of JSF and works with a standard Java web runtime. In modern projects, you will usually see it combined with Jakarta Faces, CDI for dependency injection, Bean Validation for input validation, and a server such as WildFly, Payara, Open Liberty, or Apache Tomcat with the required Jakarta libraries. In older applications, you may see the same idea using the older javax namespace instead of the newer jakarta namespace.
- JSF or Jakarta Faces: provides the component-based web framework.
- PrimeFaces: provides the rich UI widgets and Ajax-friendly behavior.
- Managed beans or CDI beans: contain page data, actions, and business calls.
- Application server: runs the web application and serves the JSF pages.
Good use cases for PrimeFaces
PrimeFaces is a strong choice for business applications where productivity, consistency, and server-side Java integration matter more than building a custom frontend framework from scratch. It is especially useful for admin dashboards, internal tools, CRUD applications, reporting screens, workflow systems, and data-entry applications. Components such as p:dataTable, p:dialog, p:autoComplete, p:calendar or p:datePicker, p:messages, and p:fileUpload can save a large amount of development time.
You should consider PrimeFaces when your team is comfortable with Java and wants to keep most application on the server. It works well when pages are form-heavy, users need reliable validation feedback, and the UI is closely tied to backend operations. It can also be a practical option for maintaining or modernizing existing JSF applications, because you can introduce PrimeFaces components gradually without rewriting the whole application.
When another approach may fit better
PrimeFaces may not be the best match for every web project. If you are building a highly interactive public-facing application with complex client-side state, offline behavior, or mobile-app-like routing, a frontend framework such as React, Angular, or Vue with REST or GraphQL services may be a better fit. PrimeFaces also assumes that you are willing to work with the JSF lifecycle, XHTML pages, component IDs, managed beans, and server-side rendering. For beginners, that model is very productive once understood, but it is different from building a pure JavaScript single-page application.
For this quick start, the goal is to use PrimeFaces in the environment where it works best: a Java web application with JSF pages, a small backing bean, and a few rich components. Once the basic setup is running, you can expand the same structure into forms, tables, dialogs, templates, navigation, validation, and database-backed screens.
Prerequisites and Development Environment Setup
Before creating a PrimeFaces page, set up a Java web development environment that can run Jakarta Faces, formerly known as JSF. PrimeFaces is a component library, so it does not run by itself; it needs a JSF runtime, a servlet container or Jakarta EE server, and a build tool to package the application. For a beginner-friendly setup, use a recent Java version, Maven, an IDE, and a lightweight server such as Apache Tomcat or a full Jakarta EE server such as Payara, WildFly, or Open Liberty.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Recommended tools
- JDK: Use Java 17 or Java 21 for new projects. Both are long-term support releases and work well with modern Jakarta EE tooling.
- Build tool: Maven is the most common choice for JSF and PrimeFaces tutorials because dependencies are declared in a pom.xml file and downloaded automatically.
- IDE: IntelliJ IDEA, Eclipse IDE for Enterprise Java, or Apache NetBeans can all create and run Maven-based web applications.
- Application server: Use Apache Tomcat 10.1+ for a servlet-container setup, or Payara 6, WildFly 30+, or Open Liberty for a fuller Jakarta EE environment.
- PrimeFaces version: Use a current PrimeFaces release that matches your Jakarta Faces version and namespace.
The most common compatibility issue for beginners is the Java EE to Jakarta EE namespace change. Older JSF applications use packages starting with javax.faces, while newer Jakarta Faces applications use jakarta.faces. Tomcat 10+, Payara 6, and modern Jakarta EE 10 servers expect the Jakarta namespace. If you copy dependencies or configuration from an older tutorial, you may accidentally mix javax and jakarta libraries, which usually causes startup errors or missing classes.
| Project style | Typical server | Namespace | Good choice for new projects |
|---|---|---|---|
| Modern Jakarta EE | Tomcat 10.1+, Payara 6, WildFly 30+ | jakarta.* |
Yes |
| Legacy Java EE | Tomcat 9, Payara 5, older WildFly | javax.* |
Only for maintaining older apps |
For this quick start, a practical setup is JDK 17, Maven, Tomcat 10.1, and a current Jakarta-compatible PrimeFaces version. After installing the JDK, confirm it from a terminal with java -version. Then confirm Maven with mvn -version. Your IDE should be configured to use the same JDK so that command-line builds and IDE builds behave consistently.
Rank #2
If you are using Tomcat, remember that it provides the servlet runtime but not the full Jakarta Faces implementation by default. That means your Maven project will need JSF-related dependencies in addition to PrimeFaces. If you use a full Jakarta EE server, some APIs may already be provided by the server, and your dependency scopes can differ. Keeping the server choice clear at the start makes the project configuration simpler in the next step, where the Maven web application and PrimeFaces dependencies are added.
Creating a Basic JSF Project
With Java, Maven, and an application server ready, the next step is to create a small Jakarta Faces project that PrimeFaces can run inside. PrimeFaces is a component library for JSF, so the project needs the usual JSF structure: a web application, a Faces servlet mapping, at least one XHTML page, and optionally a managed bean to hold page data and actions.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →A simple Maven web project is a good starting point because it keeps dependencies and packaging predictable. You can create it from your IDE using a “Maven Web Application” template, or from the command line with a standard webapp archetype. The resulting project should use WAR packaging, because it will be deployed to a Jakarta EE server such as Payara, WildFly, Open Liberty, or Apache Tomcat with the appropriate JSF libraries available.
Recommended project layout
For a beginner project, keep the structure small and easy to inspect. A typical layout looks like this:
- src/main/java for Java classes such as backing beans.
- src/main/webapp for XHTML pages, CSS files, images, and web configuration files.
- src/main/webapp/WEB-INF for files that should not be accessed directly by the browser, such as web.xml.
- pom.xml for Maven configuration, dependency versions, and build settings.
At this point, the project does not need PrimeFaces yet. First, confirm that plain JSF can serve an XHTML page. Create a page such as src/main/webapp/index.xhtml with a basic JSF view. The file should use the XHTML extension because JSF processes Facelets views through the Faces servlet. Later, this same page will be expanded with PrimeFaces tags.
Minimal web configuration
The application needs to route JSF pages through the Faces servlet. In traditional JSF projects, this is commonly done in web.xml. If your server and JSF version support annotation-based bootstrapping, the project may work with less configuration, but keeping web.xml is helpful for learning and makes the setup explicit.
| Item | Purpose |
|---|---|
| Faces Servlet | Processes JSF lifecycle requests and renders XHTML views. |
| Servlet mapping | Connects URL patterns such as *.xhtml to JSF. |
| Welcome file | Opens index.xhtml when the application root is requested. |
Use the Jakarta namespace if you are working with Jakarta Faces 3 or newer, which is typical for modern Jakarta EE servers. Older Java EE projects use the javax namespace instead. Mixing these two generations is a common source of startup errors, so keep the server version, JSF dependency, and imports aligned from the beginning.
Add a simple backing bean
Although a static page is enough to test rendering, a small backing bean makes the project feel like a real JSF application. Create a Java class under src/main/java, for example com.example.HelloBean. Mark it as a named bean and give it a request or view scope. The bean can expose a message property and a simple action method that changes the message when a button is clicked.
Once the project contains an XHTML page, a Faces servlet mapping, and a small bean, you have the base that PrimeFaces needs. Build the project with Maven and confirm that it produces a .war file without errors. In the next step, you will add the PrimeFaces dependency and replace basic JSF controls with richer UI components such as input fields, command buttons, panels, and messages.
Adding PrimeFaces Dependencies and Configuration
After creating the basic JSF project structure, the next step is to add PrimeFaces to the application. PrimeFaces is distributed as a regular Maven dependency, so you usually do not need to download JAR files manually. The exact dependency you use depends on whether your project is based on the older Java EE namespace, javax.*, or the newer Jakarta EE namespace, jakarta.*.
Free tools Windows power users keep installed
One-click scans. No signup required.
Adding the Maven dependency
For a modern Jakarta EE project using Jakarta Faces, add the PrimeFaces dependency to your pom.xml. PrimeFaces 13 and newer support Jakarta-based applications, which are commonly deployed to servers such as Payara 6, WildFly 27+, TomEE 9+, or GlassFish 7.
| Project type | Typical namespace | PrimeFaces artifact |
|---|---|---|
| Jakarta EE 9+ | jakarta.faces.* |
org.primefaces:primefaces |
| Java EE 8 or older | javax.faces.* |
Use a compatible older PrimeFaces version |
A simple Jakarta-based dependency can look like this:
<dependency>
<groupId>org.primefaces</groupId>
<artifactId>primefaces</artifactId>
<version>13.0.10</version>
</dependency>
If your project uses a Java EE 8 server such as older WildFly, Payara 5, or TomEE 8, choose a PrimeFaces version that still supports javax.faces. Mixing a Jakarta Faces runtime with a javax-based PrimeFaces version, or the reverse, commonly causes class loading errors at startup.
Checking JSF configuration
PrimeFaces builds on top of JSF, so the JSF servlet must already be mapped correctly. In a traditional web.xml configuration, the Faces servlet is usually mapped to *.xhtml or /faces/*. For a quick start project, mapping directly to XHTML files is simple and easy to test.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>jakarta.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>*.xhtml</url-pattern>
</servlet-mapping>
If your server and JSF version support annotation-based initialization, your project may work without much XML configuration. Even then, keeping a small web.xml during the learning phase makes the request flow easier to understand: browser requests for .xhtml pages are handled by JSF, and PrimeFaces components are rendered as part of the JSF lifecycle.
Optional PrimeFaces settings
PrimeFaces works without extra settings, but a few context parameters are useful in development. Add them to web.xml if you want clearer error output and easier debugging while building your first pages.
jakarta.faces.PROJECT_STAGE: set toDevelopmentwhile learning and switch toProductionbefore deployment.primefaces.THEME: selects a built-in or installed theme, such assaga,vela, orarya, depending on your PrimeFaces version.primefaces.CLIENT_SIDE_VALIDATION: enables client-side validation support for many input components.
<context-param>
<param-name>jakarta.faces.PROJECT_STAGE</param-name>
<param-value>Development</param-value>
</context-param>
<context-param>
<param-name>primefaces.THEME</param-name>
<param-value>saga</param-value>
</context-param>
At this point, rebuild the project with Maven so the PrimeFaces library is downloaded and packaged with the application. In the next step, you can create an XHTML page that declares the PrimeFaces namespace and uses components such as p:button, p:inputText, and p:panel.
Building Your First PrimeFaces Page
With the JSF project created and the PrimeFaces dependency available, the next step is to build a small page that proves the UI library is working. A PrimeFaces page is still a JSF Facelets page, usually saved with an .xhtml extension, but it uses the PrimeFaces component namespace to render richer widgets such as styled buttons, input fields, panels, tables, dialogs, and messages.
Rank #4
Create a page such as index.xhtml under your web application folder, commonly src/main/webapp in a Maven project. The page should declare the standard JSF HTML namespace and the PrimeFaces namespace. A minimal page can include a form, an input field, a command button, and a messages component so you can submit data and display feedback.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:h="jakarta.faces.html"
xmlns:p="http://primefaces.org/ui">
<h:head>
<title>PrimeFaces Quick Start</title>
</h:head>
<h:body>
<h:form>
<p:panel header="My First PrimeFaces Page">
<p:messages id="messages" />
<p:outputLabel for="name" value="Your name" />
<p:inputText id="name" value="#{helloBean.name}" />
<p:commandButton value="Say Hello"
action="#{helloBean.sayHello}"
update="messages greeting" />
<p:separator />
<h:panelGroup id="greeting">
<h:outputText value="#{helloBean.greeting}" />
</h:panelGroup>
</p:panel>
</h:form>
</h:body>
</html>
This page references a managed bean named helloBean. In a Jakarta Faces application, this bean is often a CDI bean. Place it in your Java source folder, for example under src/main/java, using a package name that matches your project. The bean stores the submitted name and prepares a greeting when the button is clicked.
package com.example;
import jakarta.enterprise.context.RequestScoped;
import jakarta.faces.application.FacesMessage;
import jakarta.faces.context.FacesContext;
import jakarta.inject.Named;
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errors@Named
@RequestScoped
public class HelloBean {
private String name;
private String greeting;
public void sayHello() {
if (name == null || name.trim().isEmpty()) {
FacesContext.getCurrentInstance().addMessage(null,
new FacesMessage(FacesMessage.SEVERITY_WARN,
"Please enter your name", null));
greeting = "";
return;
}
greeting = "Hello, " + name + "! Welcome to PrimeFaces.";
FacesContext.getCurrentInstance().addMessage(null,
new FacesMessage("Greeting created successfully"));
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute public String getGreeting() {
return greeting;
}
}
The most PrimeFaces element here is <p:commandButton>. Unlike a plain HTML button, it can trigger a JSF action and update selected parts of the page with Ajax. The update="messages greeting" attribute tells PrimeFaces to refresh only the messages area and the greeting output after the request completes, instead of reloading the whole page.
What to Check on the Page
- Namespace: The PrimeFaces namespace must be declared as
xmlns:p="http://primefaces.org/ui". - Form: Input components and command components should be placed inside an
<h:form>. - Bean name: The expression
#{helloBean}must match the CDI name of the bean. - Ajax update targets: Components referenced in
updateneed stable IDs, such asmessagesandgreeting.
At this point, you have a working PrimeFaces view that accepts user input, calls server-side Java code, and updates part of the page dynamically. From here, you can replace the simple greeting with more useful features such as a data table, a dialog, form validation, or navigation to another JSF page.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Running and Testing the Application
With the JSF page, managed bean, and PrimeFaces dependency in place, the next step is to deploy the application and verify that the page renders correctly in a browser. If you are using Maven, first run a clean build from the project root to confirm that the application compiles and all dependencies are resolved. For a typical WAR-based project, the command is mvn clean package. A successful build should create a .war file under the target directory.
Best Value
Deploy the application to your chosen Jakarta EE or Java EE server, such as Apache Tomcat, WildFly, Payara, or Open Liberty. In an IDE like IntelliJ IDEA, Eclipse, or NetBeans, this is usually done by creating a server run configuration and selecting the project artifact to deploy. If you are deploying manually, copy the generated WAR file into the server’s deployment directory. For example, Tomcat uses the webapps folder, while WildFly commonly uses the standalone/deployments directory.
Opening the PrimeFaces Page
After the server starts, open the application in your browser using the server URL, application context path, and JSF page name. If your project is named primefaces-quickstart and your page is index.xhtml, the URL may look like this: http://localhost:8080/primefaces-quickstart/index.xhtml. The exact path can vary depending on your server configuration and artifact name, so check the deployment log if the page is not found.
You should see the PrimeFaces components rendered with styling instead of plain HTML inputs. If you added a form with a text field, command button, and message component, test the interaction by entering a value and clicking the button. The page should submit through JSF, call the managed bean action or update the bound property, and refresh the target component if you configured an Ajax update.
Common Checks During Testing
- Page loads but styling is missing: confirm that the PrimeFaces dependency is included and that JSF resource handling is not blocked by a custom servlet mapping or security rule.
- 404 error: verify the application context path, page name, deployment status, and whether your JSF servlet mapping expects URLs such as /index.xhtml or /faces/index.xhtml.
- Managed bean not found: check the bean annotation, package scanning, bean name, and whether you are using the correct namespace for Jakarta or older Javax APIs.
- Button click does nothing: make sure the PrimeFaces command component is inside an h:form and that the update target points to a valid component ID.
Once the first page works, try a small change to confirm your development cycle. Edit the XHTML file, restart or redeploy if your server requires it, then refresh the browser. Many IDE and server combinations support hot deployment for XHTML changes, while Java bean changes may need a rebuild or restart. This quick feedback loop is useful when you start adding more PrimeFaces widgets, validation, navigation, and database-backed data tables.
Frequently Asked Questions
Do I need Jakarta EE or can I use older Java EE with PrimeFaces?
PrimeFaces has versions for both older Java EE/JSF projects and newer Jakarta EE/Jakarta Faces projects. If your server uses the javax.* namespace, choose a PrimeFaces version that supports Java EE; if it uses jakarta.*, use a Jakarta-compatible PrimeFaces version. Matching the PrimeFaces version to your application server is one of the most common setup issues for beginners.
Which application server should I use for a first PrimeFaces project?
For a beginner project, Payara, WildFly, or TomEE are common choices because they support JSF/Jakarta Faces well. If you are following a Jakarta EE setup, make sure the server version supports the same Jakarta EE version used by your dependencies. For a simple tutorial project, using a server with built-in Faces support can reduce configuration work.
Do I need to install JSF separately when using PrimeFaces?
PrimeFaces is a component library built on top of JSF or Jakarta Faces, so the Faces runtime must be available. Some application servers already include it, while servlet containers such as Tomcat usually need the Faces libraries added manually. Check your server documentation before adding extra dependencies to avoid duplicate library conflicts.
What files are usually required for a minimal PrimeFaces page to work?
A minimal PrimeFaces application usually needs a JSF page such as index.xhtml, the PrimeFaces dependency, a Faces servlet mapping, and a backing bean if the page uses server-side data or actions. Many Jakarta EE servers can run with very little XML configuration, but older JSF projects may still use web.xml. The page must also declare the PrimeFaces XML namespace before using components such as p:button, p:inputText, or p:dataTable.
What should I build after getting the first PrimeFaces page running?
A good next step is to add a managed bean and bind form inputs to Java properties. After that, try common components such as tables, dialogs, messages, menus, and AJAX-enabled buttons. These features will help you understand how PrimeFaces connects the XHTML view, server-side Java code, and the JSF request lifecycle.
Bottom Line
PrimeFaces gives JSF developers a fast way to build polished, component-rich web interfaces with less boilerplate. Once your Java/Jakarta EE environment, dependencies, configuration, and first XHTML page are in place, you have the foundation for a working PrimeFaces application.
Your next step is to expand the sample page with managed beans, validation, templates, and more PrimeFaces components such as data tables, dialogs, and forms. Keep experimenting with small features first, then gradually combine them into a complete application.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
