Today we will look into the Primefaces FileUpload component. HTML provides you file input tag to select the file, but we need a lot more to upload a file to the server. Primefaces has removed that burden by providing you a ready-made FileUpload component that help you in creating beautiful UI with backend support for upload files to the server.

Primefaces FileUpload

We will look into the Primefaces FileUpload component features that you can use in your application.

This tutorial assumes that you have basic knowledge of Primeface, if not please go through Primefaces Example.

Primefaces FileUpload Basic Info

Tag fileUpload
Component Class org.primefaces.component.fileupload.FileUpload
Component Type org.primefaces.component.FileUpload
Component Family org.primefaces.component
Renderer Type org.primefaces.component.FileUploadRenderer
Renderer Class org.primefaces.component.fileupload.FileUploadRenderer

Primefaces FileUpload Attributes

Name Default Type Description
id null String Unique identifier of the component.
rendered true boolean Boolean value to specify the rendering of the component, when set to false component will not be rendered
binding null Object An el expression that maps to a server side UIComponent instance in a backing bean
value null Object Value of the component than can be either an EL expression of a literal text
converter null Converter/String An el expression or a literal text that defines a converter for the component. When it’s an EL expression, it’s resolved to a converter instance. In case it’s a static text, it must refer to a converter id.
immediate false Boolean When set true, process validations logic is executed at apply request values phase for this component
required false Boolean Marks component as required.
validator null MethodExpr A method expression that refers to a method validating the input
valueChangeListener null MethodExpr A method expression that refers to a method for handling a valueChangeEvent
requiredMessage null String Message to be displayed when required field validation fails
converterMessage null String Message to be displayed when conversion fails.
validatorMessage null String Message to be displayed when validation fails.
widgetVar null String Name of the client side widget.
update null String Component(s) to update after fileupload completes.
process null String Component(s) to process in fileupload request.
fileUploadListener null MethodExpr Method to invoke when a file is uploaded.
multiple false Boolean Allows choosing of multi file uploads from native
auto false Boolean When set to true, selecting a file starts the upload process implicitly
label Choose String Label of the browse button.
allowTypes null String Regular expression for accepted file types,
sizeLimit null Integer Individual file size limit in bytes.
fileLimit null Integer Maximum number of files allowed to upload.
style null String Inline style of the component.
styleClass null String Style class of the component.
mode advanced String Mode of the fileupload, can be simple or advanced.
uploadLabel Upload String Label of the upload button.
cancelLabel Cancel String Label of the cancel button.
invalidSizeMessage null String Message to display when size limit exceeds.
invalidFileMessage null String Message to display when file is not accepted.
fileLimitMessage null String Message to display when file limit exceeds.
dragDropSupport true Boolean Specifies dragdrop based file selection from filesystem, default is true and works only on supported browsers
onstart null String Client side callback to execute when upload begins.
onerror null String Callback to execute if fileupload request fails.
oncomplete null String Client side callback to execute when upload ends.
disabled false Boolean Disables component when set true.
messageTemplate {name} {size} String Message template to use when displaying file validation errors
previewWidth 80 Integer Width for image previews in pixels.

Primefaces File Upload Example

For making use of FileUpload, you have to provide the FileUpload engine by adding primefaces.UPLOADER web deployment paramater that might take the below values:


  1. auto: This is the default mode and Primefaces tries to detect the best method by checking the runtime environment, if JSF runtime is at least 2.2 native uploader is selected, otherwise commons.
  2. native: Native mode uses servlet 3.x Part API to upload the files and if JSF runtime is less 2.2 an exception is being thrown.
  3. commons: This option chooses commons fileUpload, it requires the following filter configuration in your deployment descriptor.


Note the servlet-name should match the configured name of the JSF servlet which is Faces Servlet in this case. Alternatively, you can do a configuration based on URL-pattern as well.

Primefaces Simple File Upload

Simple file upload mode works in legacy browsers, with a file input whose value should be an UploadedFile instance. Ajax uploads are not supported in the simple upload. Look below for these files required for making a simple file upload sample.




As a summary:

  1. Primefaces FileUpload engine that’s used is auto.
  2. fileUpload component’s value attribute associated with the UploadedFile instance.
  3. Using of fileUpload requires including the fileUpload component within a form, its enctype is multipart/form-data.
  4. Dummy action provided has used to print out the name and size of the uploaded file.

Where, the result of demo will be: Simple input button has been rendered into your browser.



And once you’ve clicked on the Dummy Action a dummy action method is executed and the information of uploaded file gets printed into your console like below.


Primefaces Advanced File Upload

FileUpload component provides you a simple view and an advanced view. Choosing of advanced view makes the only available way for accessing uploaded files is through the FileUploadListener. The listener will be processed as soon as the file is uploaded and a FileUploadEvent has been passed into listener as a parameter.

Look below at the required files that help you using advanced mode.


As a summary:

  1. Neither web.xml nor pom.xml have been mentioned, cause they haven’t changed.
  2. FileUpload component’s value attribute associated with the UploadedFile instance, as the component also listened by the FileUploadListener.
  3. FileUploadListener receives a FileUploadEvent as a parameter.
  4. Once you’ve clicked on the Upload action, the FileUploadListener will be executed and a FileUploadEvent has been created and passed.

Where, the result of demo will be a new view of upload component with two additional buttons; one for upload and the latter for cancel.


It’s important to notice the following points as a result of execution:

  1. The file uploaded is passed within the FileUploadEvent and it can be accessed by invoking e.getFile() against event object which returns an UploadedFile instance.
  2. The upload process would be cancelling totally, if you’ve clicked on Cancel instead of Upload. Canceling the upload will prevent the listener from getting invoked.

Primefaces Multiple File Uploads

Uploading multiple files using the FileUpload component is applicable so that multiple files can be selected from browser dialog. Multiple uploads are not supported in legacy browsers. Set multiple attribute to true enabling multiple selections of files, however, multiple selections of files doesn’t mean all files will be sent into the server using one request. However, they will be sent one by one.

Look below at the required change that makes multiple selections applicable.


Where, the result of executing the application looks like below:

It’s important to notice the following points from the demo:

  1. Cancelling the upload using Cancel button, should lead us into canceling the upload process of all files.
  2. Clicking into icon X that’s beside every single file that will be uploading, cause the corresponding file uploaded to be canceled only.
  3. Once you’ve clicked on Upload action, the listener will be invoked by the number of files that get loaded.

Primefaces Auto File Upload

The default behavior requires users to trigger the upload process, you can change this way by setting auto to true. Auto uploads are triggered as soon as files are selected from the dialog.

Look below at the required change that makes auto upload applicable.


Where, the result of executing the application looks like below:

Once you’ve clicked Open into your browser window, Uploading process has been started instantly.

Primefaces File Upload Partial Page Update

After the fileUpload process completes you can use the Primefaces PPR (Partial Page Render) to update any component on the page. FileUpload is equipped with the update attribute for this purpose. Following example displays a “File Uploaded Successfully” message using the growl component after file upload. Growl component will be discussed later when coming into messages.

The following fragment of codes helps you display a message once the file has been uploaded.


Where, the result of execution looks like below:


A message has been added into FacesContext and the FileUpload component defines the update attribute which will cause the message to be rendered through Ajax mechanism. Ajax behavior will be discussed later in a separate tutorial.

File Upload Filters

Users can be restricted to only select the file types you’ve configured, the example below demonstrates how to accept images only.


And the result of execution looks like below

Primefaces File Upload Size Limit & File Limit

Sometimes, you need to restrict the size of the uploaded file or the number of files to be uploaded. Doing such these restrictions aren’t big issue with Primefaces FileUpload component. You can achieve these restrictions by providing sizeLimit & fileLimit attributes respectively against FileUpload itself.

Following the code fragments that keep your users restricted:


When you try to upload more than three files or file its size exceeds the limit an error messages will be displayed like below:

Primefaces File Upload Validation Message

invalidFileMessage, invalidSizeMessage and fileLimitMessage options are provided to display validation messages to the users. You can provide whatever you want of messages for those validations. Look below at the provided example.


And the messages should look like below:

If you’ve noticed the messages have been changed and they’re provided different text values. If you notice the managed bean code, we are not doing anything with the file. However in real life situations, we can use UploadedFile getInputstream() method to get the file data and save it as file on server or database.

Primefaces FileUpload Summary

This tutorial intended to provide you a full detailed explanation about using of FileUpload Primefaces component. FileUpload component equipped with a lot of features that keep your focus on the business instead of trying to implement something similar. You can download the sample project from below link and use other fileUpload attributes to learn more.

By admin

Leave a Reply

%d bloggers like this: