File Upload

Overview

A common use case in enterprise applications is allowing the user to upload files for your app to process. Depending on the use case, the front end may send the uploaded files to a server for processing, or it may process the files locally.

Some use cases allow the user to upload multiple files at once, while others restrict the user to uploading only one file.

Most use cases require the user to upload only particular file types, say a PDF file or an image file. Your app should ensure that the files selected by the user correspond to any file type constraints.

Your app should impose some limit on the file size for uploaded files, for storage, bandwidth, and security reasons. The file size limit should be large enough to allow users to accomplish their task.

There are two user experiences for file upload: standard and basic. Each is described below.

Standard file upload

The standard file upload provides a comprehensive file upload experience for the user. This is the preferred approach.

The standard file upload displays:

• A Select Files button that allows the user to select files to upload.
• An Upload button that allows the user to start the upload process. This button is disabled until the user has selected files to upload.
• A Cancel button that allows the user to clear the list of files to upload. This button is disabled until the user has selected files to upload.
• A box that contains all information about uploaded files, along with a “Drag files here” message that helps the user understand that they can drag and drop files to upload.
• A help message below the box that specifies the file type and file size requirements.

The user has two options for indicating which files to upload:

• The user can press the Select Files button. The native Open dialog box displays. The user selects the file(s) to upload, then presses the Open button in the Open dialog box.
• The user can drag and drop files onto the file upload box.

The standard file upload displays a list of the files selected to upload, with the file name and file size indicated. It displays a delete button next to each file in the list; the user can press this button to remove that file from the list.

If the user selects a file that is of the wrong file type or is too large in size, display a validation error.

From here, the user can:

• Press the Select Files button again.
  • If this use case supports uploading multiple files, any new files selected by the user will be added to the list of files to upload.
  • Otherwise the user selects a single file that replaces the current list.
• Press the Upload button to begin the process of uploading the selected files.
• Press the Cancel button to remove all files from the list.

After the user presses the Upload button to start the upload process, display a progress bar that shows the file upload progress. Note that this progress bar shows the upload process for all selected files rather than for each individual file.

After the upload completes, display a list of all files uploaded, with the file name and file size for each.

It can be helpful to also display a popup notification that lets the user know that the file upload is complete.

From here, the user can start this process over and upload additional files by pressing the Select Files button again, if the use case supports this. This allows the user to upload files in batches, which may be appropriate if, say, they forgot to include a relevant file when uploading the previous batch.

After the user selects more files to upload, display both the list of new files to upload and the list of previously uploaded files within the file upload box.

After the new batch of files has been uploaded, the list of uploaded files now includes the files from both batches.

The user can repeat this process until all relevant files have been uploaded.

Basic file upload

The basic file upload displays an Upload button.

The user has two options for indicating which files to upload:

• The user can press the Upload button. The native Open dialog box displays. The user selects the file(s) to upload, then presses the Open button in the Open dialog box.
• The user can drag and drop files onto the Upload button.

Your app now has a list of files to be uploaded. Validate the file type and file size of all files selected to upload.

If the selected files fail the validation, display a standard validation error beneath the “Upload” button that identifies all errors.

If the files pass the validation, then upload the files and display a notification that lets the user know that the file upload is complete. This will typically be a popup notification.

Process the uploaded files. This may involve displaying additional information in the UI, depending on the use case.

Development

Web component development

Component reference

p-fileupload

Implementation

Begin by importing the FileUploadModule module into your application.

// import into app.module
import { FileUploadModule } from 'primeng/fileupload';

@NgModule({
    imports: [
        ...
        FileUploadModule,
        ...
    ]
})

export class AppModule(){}

Add a p-fileupload instance to your view.

The properties you’ll set in the component depend on which of the two file upload experiences your app uses, described in the sections below:

Use the standard file upload experience for most use cases. This is the preferred approach. Use the basic file upload experience if your app needs even more control over the file upload process and user experience.

Implementing the standard file upload

The p-fileupload component supports three modes: Advanced, Basic, and Basic with Auto. Use the Advanced mode to implement the Standard file upload, which is our preferred file upload experience. Advanced mode is the default, so you can omit this property if you choose.

<p-fileUpload mode="advanced" ...

The standard file upload experience (the “Advanced” mode) provides a more comprehensive user experience for your users, as well as packaging much of the functionality for you, which means you don’t have to do as much work in your app.

The packaged functionality includes:

• The component automatically validates the file type and file size constraints specified by your app, displaying a styled validation error (using an inline notification) within the component when needed.
• The component automatically displays an embedded progress bar.
• The component allows the user to upload files in batches.
• The component displays a list of files to be uploaded, with the file name, file size, and a delete button that allows the user to remove the file from the list of files to be uploaded.
• The component displays a list of files already uploaded, with the file name and file size.

The actions your app needs to take external to this component in Advanced mode include:

• Your app should display help text below the component that describes file type and file size constraints.
• Your app specifies a template for the list of files already uploaded. The Angular sample app shows the preferred approach for this.
• Your app should display a popup notification each time the file upload succeeds.

In order to set up a simple implementation of the standard file upload, set the button copy with the chooseLabel attribute. Create an ng-template to structure the list of files to be uploaded. Within the template, create a new instruction div with a rui-icon and instruction text. This will help users recognize drag/drop functionality.

<p-fileUpload mode="advanced" chooseLabel="Select Files" ...>
    <ng-template pTemplate="content">
        <div *ngIf="uploadedFiles.length">
            <div style="margin: 10px 0 5px 0"><strong>Files Uploaded:</strong></div>
            <ul>
                <li *ngFor="let file of uploadedFiles">
                    <span class="rui-bright-text-label">{{file.name}}</span>
                    <span class="rui-regular-text-label"> - {{file.size}} bytes</span>
                </li>
            </ul>
        </div>
        <div class="instructions-container">
            <rui-icon iconType="Upload" jhaSize="24px" class="instructions-icon"></rui-icon>
            <span class="instructions-text">Drag files here</span>
        </div>
    </ng-template>
</p-fileUpload>

Additional CSS is required to layout the instruction div correctly. Apply the following to the component view CSS.

.instructions-container {
    margin: 20px 0 15px 0;
    opacity: 0.5;
    display: flex;
    flex-direction: column;
    justify-content: center;
}

.instructions-icon {
    margin: 0 auto 5px auto;
    opacity: 0.5;
}

.instructions-text {
    text-align: center;
}

Multiple files

Set the multiple property to a truthy or falsy value to specify whether the user can upload multiple files at once. The native Open dialog box will enforce the single vs multiple setting. Their documentation indicates that this is a Boolean property, but their examples show multiple="multiple", which is technically a truthy value.

<p-fileUpload [multiple]="true" ...

Accepted file types

Set the accept property to a value that indicates what types of files this upload will accept. The native Open dialog box will by default only list files of that type. The component displays an error notification if the user selects a different file type to upload. You can see examples of appropriate values here.

<p-fileUpload accept="image/*" ...

Max file size

Set the maxFileSize property to a numeric value that indicates the max file size in bytes that can be uploaded. The component displays an error notification if the user selects a file whose size is larger than this value.

<p-fileUpload maxFileSize="1000000" ...

Moving the bytes

You can specify if uploaded files should get automatically posted to a server URL or if your app will handle the file upload process manually.

Set the url property if you want the component to automatically upload the files to a server URL.

<p-fileUpload url="https://www.primefaces.org/primeng/showcase/upload.php" ...

Otherwise set the customUpload property to true and define a handler for the uploadHandler event if your app will manually upload the files.

<p-fileUpload customUpload="true" (uploadHandler)="ManualUpload($event)" ...

Thumbnails are hidden

The base component in Advanced mode attempts to display a small thumbnail for image files in the list of files to be uploaded, reserving a blank space for all other file types. This leaves an awkward gap in the list for all other file types, so the enterprise theming hides the leftmost div in the list since that contains the thumbnail.

Implementing the basic file upload

The p-fileupload component supports three modes: Advanced, Basic, and Basic with Auto. Use the Basic with Auto mode to implement the Basic file upload.

<p-fileUpload mode="basic" [auto]="true" chooseLabel="Upload" ...

In this mode, the component displays a Upload button that allows the user to select one or more files to upload. These files are uploaded immediately after the user selects them, with no further user experience displayed by the component.

Note that this mode does not display validation errors, a progress bar, the list of files to upload, or the list of files to be uploaded. Your app must display all user experience beyond the Upload button itself.

The actions your app needs to take external to this component in “Basic with Auto” mode include:

• Your app should display Help text below the component that describes file type and file size constraints
• Your app displays any validation errors related to the file type and file size constraints below the component.
• Your app should display a popup notification each time the file upload succeeds.

Multiple files

Set the multiple property to a truthy or falsy value to specify whether the user can upload multiple files at once. The native Open dialog box will enforce the single vs multiple setting. Their documentation indicates that this is a Boolean property, but their examples show multiple="multiple", which is technically a truthy value.

<p-fileUpload [multiple]="true" ...

Moving the bytes

You can specify if uploaded files should get automatically posted to a server URL or if your app will handle the file upload process manually.

Set the url property if you want the component to automatically upload the files to a server URL.

<p-fileUpload url="https://www.primefaces.org/primeng/showcase/upload.php" ...

Otherwise set the customUpload property to true and define a handler for the uploadHandler event if your app will manually upload the files.

<p-fileUpload customUpload="true" (uploadHandler)="ManualUpload($event)" ...

Angular wrapper development

Wrapper reference

p-fileupload

Implementation

Begin by importing the FileUploadModule module into your application.

// import into app.module
import { FileUploadModule } from 'primeng/fileupload';

@NgModule({
    imports: [
        ...
        FileUploadModule,
        ...
    ]
})

export class AppModule(){}

Add a p-fileupload instance to your view.

The properties you’ll set in the component depend on which of the two file upload experiences your app uses, described in the sections below:

Use the standard file upload experience for most use cases. This is the preferred approach. Use the basic file upload experience if your app needs even more control over the file upload process and user experience.

Implementing the standard file upload

The p-fileupload component supports three modes: Advanced, Basic, and Basic with Auto. Use the Advanced mode to implement the Standard file upload, which is our preferred file upload experience. Advanced mode is the default, so you can omit this property if you choose.

<p-fileUpload mode="advanced" ...

The standard file upload experience (the “Advanced” mode) provides a more comprehensive user experience for your users, as well as packaging much of the functionality for you, which means you don’t have to do as much work in your app.

The packaged functionality includes:

• The component automatically validates the file type and file size constraints specified by your app, displaying a styled validation error (using an inline notification) within the component when needed.
• The component automatically displays an embedded progress bar.
• The component allows the user to upload files in batches.
• The component displays a list of files to be uploaded, with the file name, file size, and a delete button that allows the user to remove the file from the list of files to be uploaded.
• The component displays a list of files already uploaded, with the file name and file size.

The actions your app needs to take external to this component in Advanced mode include:

• Your app should display help text below the component that describes file type and file size constraints.
• Your app specifies a template for the list of files already uploaded. The Angular sample app shows the preferred approach for this.
• Your app should display a popup notification each time the file upload succeeds.

In order to set up a simple implementation of the standard file upload, set the button copy with the chooseLabel attribute. Create an ng-template to structure the list of files to be uploaded. Within the template, create a new instruction div with a jha-icon and instruction text. This will help users recognize drag/drop functionality.

<p-fileUpload mode="advanced" chooseLabel="Select Files" ...>
    <ng-template pTemplate="content">
        <div *ngIf="uploadedFiles.length">
            <div style="margin: 10px 0 5px 0"><strong>Files Uploaded:</strong></div>
            <ul>
                <li *ngFor="let file of uploadedFiles">
                    <span class="jha-bright-text-label">{{file.name}}</span>
                    <span class="jha-regular-text-label"> - {{file.size}} bytes</span>
                </li>
            </ul>
        </div>
        <div class="instructions-container">
            <jha-icon jhaIconType="Upload" jhaSize="24px" class="instructions-icon"></jha-icon>
            <span class="instructions-text">Drag files here</span>
        </div>
    </ng-template>
</p-fileUpload>

Additional CSS is required to layout the instruction div correctly. Apply the following to the component view CSS.

.instructions-container {
    margin: 20px 0 15px 0;
    opacity: 0.5;
    display: flex;
    flex-direction: column;
    justify-content: center;
}

.instructions-icon {
    margin: 0 auto 5px auto;
    opacity: 0.5;
}

.instructions-text {
    text-align: center;
}

Multiple files

Set the multiple property to a truthy or falsy value to specify whether the user can upload multiple files at once. The native Open dialog box will enforce the single vs multiple setting. Their documentation indicates that this is a Boolean property, but their examples show multiple="multiple", which is technically a truthy value.

<p-fileUpload [multiple]="true" ...

Accepted file types

Set the accept property to a value that indicates what types of files this upload will accept. The native Open dialog box will by default only list files of that type. The component displays an error notification if the user selects a different file type to upload. You can see examples of appropriate values here.

<p-fileUpload accept="image/*" ...

Max file size

Set the maxFileSize property to a numeric value that indicates the max file size in bytes that can be uploaded. The component displays an error notification if the user selects a file whose size is larger than this value.

<p-fileUpload maxFileSize="1000000" ...

Moving the bytes

You can specify if uploaded files should get automatically posted to a server URL or if your app will handle the file upload process manually.

Set the url property if you want the component to automatically upload the files to a server URL.

<p-fileUpload url="https://www.primefaces.org/primeng/showcase/upload.php" ...

Otherwise set the customUpload property to true and define a handler for the uploadHandler event if your app will manually upload the files.

<p-fileUpload customUpload="true" (uploadHandler)="ManualUpload($event)" ...

Thumbnails are hidden

The base component in Advanced mode attempts to display a small thumbnail for image files in the list of files to be uploaded, reserving a blank space for all other file types. This leaves an awkward gap in the list for all other file types, so the enterprise theming hides the leftmost div in the list since that contains the thumbnail.

Implementing the basic file upload

The p-fileupload component supports three modes: Advanced, Basic, and Basic with Auto. Use the Basic with Auto mode to implement the Basic file upload.

<p-fileUpload mode="basic" [auto]="true" chooseLabel="Upload" ...

In this mode, the component displays a Upload button that allows the user to select one or more files to upload. These files are uploaded immediately after the user selects them, with no further user experience displayed by the component.

Note that this mode does not display validation errors, a progress bar, the list of files to upload, or the list of files to be uploaded. Your app must display all user experience beyond the Upload button itself.

The actions your app needs to take external to this component in “Basic with Auto” mode include:

• Your app should display Help text below the component that describes file type and file size constraints
• Your app displays any validation errors related to the file type and file size constraints below the component.
• Your app should display a popup notification each time the file upload succeeds.

Multiple files

Set the multiple property to a truthy or falsy value to specify whether the user can upload multiple files at once. The native Open dialog box will enforce the single vs multiple setting. Their documentation indicates that this is a Boolean property, but their examples show multiple="multiple", which is technically a truthy value.

<p-fileUpload [multiple]="true" ...

Moving the bytes

You can specify if uploaded files should get automatically posted to a server URL or if your app will handle the file upload process manually.

Set the url property if you want the component to automatically upload the files to a server URL.

<p-fileUpload url="https://www.primefaces.org/primeng/showcase/upload.php" ...

Otherwise set the customUpload property to true and define a handler for the uploadHandler event if your app will manually upload the files.

<p-fileUpload customUpload="true" (uploadHandler)="ManualUpload($event)" ...

Design

Figma design

To show the standard file upload (which is the typical case), add a File Upload component to the artboard.

To show the basic file upload, add a secondary text button to the artboard. Change its text to “Upload”. Resize the button to fit the text.

Adobe XD design

To show the standard file upload (which is the typical case), add a File Upload component to the artboard.

To show the basic file upload, add a secondary text button to the artboard. Change its text to “Upload”. Resize the button to fit the text.