Skip to content
Stable

File Upload Component

FileUpload allows a user to upload one or more files. This component would typically be used when a member needs to submit receipts, images or documents required to validate a claim or utilise online services. It supports both drag-and-drop functionality on desktop/tablet breakpoints, and upload via the native file browser on all platforms.

Installation

bash
npm install @nib/file-upload-component

As a form input, this component can be wrapped in @nib-components/form-control to provide an accessible label, help text, and validation styling.

Usage

jsx
import {FileUploadComponent} from '@nib/file-upload-component';
import FormControl from '@nib-components/form-control';
import {fileUploadUrl} from '../constants';
// `form` comes from formik
export const SupportingDocs = ({form}) => {
const [filesOnParent, setFilesOnParent] = useState([]);
const [filesReadyForUpload, setFilesReadyForUpload] = useState(false);
useEffect(() => {
form.setFieldValue('files', filesOnParent);
form.setFieldValue('filesReadyForUpload', filesReadyForUpload);
}, [filesOnParent, filesReadyForUpload]);
return (
<FormControl label="File upload" help="Supported file types: png, pdf, jpg, etc. (<5mb)">
<FileUploadComponent
acceptedFileTypes=".pdf,.jpg,.gif"
setFilesOnParent={setFilesOnParent}
filesOnParent={filesOnParent}
filesReadyForUpload={filesReadyForUpload}
setFilesReadyForUpload={setFilesReadyForUpload}
gatewayEndpoint={fileUploadUrl}
>
<Copy align="center">
Accepted file types: PDF, JPG and GIF.
</Copy>
</FileUploadComponent>
</FormControl>
);
};

Interactive demo

Select your files to upload
Drag and drop your files
here to upload
or

Accepted file types: PDF, JPG and GIF.

jsx

Props

PropTypeDefaultDescription
acceptedFileTypesstring"image/*,.pdf"Defines the file types that can be selected for uploading.
gatewayEndpointstringfalseDefines the API Gateway endpoint that does a GET request for an upload link.
setFilesOnParentfunctionfalseThe set function of a React useState, when files have a status of Processing Complete the library will send an array back to the parent using the setFilesOnParent method.
filesOnParentarray[]The variable of a React useState. This is used to compare to the files the library is trying to update. It does not affect the file upload in any way (eg., the library updates the filesOnParent, but filesOnParent has no affect on what the library is doing).
childrennodePlace any relevant content here. Often used to describe allowed file types and sizes.

States & Behaviour

This component has a range of states that change dynamically as the user interacts with the component. Both the target area and individual file avatars respond contextually to user input to communicate progress and validation of uploads.

Target area

Empty (default)

When no files have been uploaded, or all uploaded files have been deleted, the user will be presented with this default target area. Any children of the <FileUploadComponent> will be populated below the Browse Files button. We recommend using the help prop in the parent <FormControl> wrapper to inform the user of the nature of files needed to progress, and suggesting required file size and/or types as children of the <FileUploadComponent>.

File Upload - Empty state
Default empty state of file upload component.

Empty (Mobile Responsive)

As above, an empty target area will load or revert to this state, however on at xs and sm breakpoints, the support copy is modified to remove reference to the drag-and-drop functionality. Drag-and-drop is still technically retained, but given that this will typically be presented in a mobile environment, this state directs the user's attention toward the native file browser of their device.

File Upload - Empty state (mobile)
Default empty state of file upload component (mobile).

Drag-and-drop

This state will appear when a file (or files) are dragged from outside the browser window over the target area. On release, the target area will transition to the Ideal state, with any uploaded files appearing in a stacked list.

File Upload - Drag over state
Drag over state of file upload component.

Ideal state

This state will appear when a file (or files) are dragged from outside the browser window over the target area. On release, the target area will transition to the Ideal state, with any uploaded files appearing in a stacked list. Additional files can be added via drag-and-drop or via the Upload new file button.

File Upload - with files
File upload component with 3 files.

Ideal (Mobile Responsive)

File Upload - with files (mobile)
File upload component with 3 files (mobile).

File avatars

Loading

This state will appear while a file is being uploaded. Once complete, it will validate the upload against the supplied parameters and transition to either an Ideal or Error state. A pending upload can be cancelled by the user via the icon on the right. File names will appear truncated if they exceed the bounds of the parent container.

File Attachment - loading state
A File Attachment that is in a loading state.

Success (ideal)

A successfully uploaded file will appear as shown. Users can delete already-uploaded files by clicking/tapping the delete icon.

File Attachment - success state
A File Attachment that is in a successful state.

Error

When an uploaded file fails or does not meet the supplied size/format parameters, users will be presented with this state. In the context of a failed upload, the refresh icon will retry the upload, whereas if it doesn’t meet parameters, the icon will prompt the user to select a new file via the file browser. File names will appear truncated as referenced above, but error messaging will wrap and cause the parent container to grow vertically.

File Attachment - error state
A File Attachment that is in an error state.

Mobile (Responsive)

On mobile (xs & sm) breakpoints, the left-hand icon or loader is omitted to preserve horizontal screen real estate. Truncation and text-wrap behaviours are retained from the default variants.

File Attachment - all states (mobile)
File Attachments (mobile).

Validations & Errors

While some validation happens in real-time as files are uploaded, if a field is left empty or contains invalid files on submission of a form containing FileUpload, error messaging must be supplied to the FileUpload’s FormControl wrapper. Error messaging on failed submission will appear as below.

Using Form Control validation with File Upload Component
Wrapping the File Upload Component in a Form Control for validaiton.
Using Form Control validation with File Upload Component
Wrapping the File Upload Component in a Form Control for validaiton.

Considerations

The <FileUploadComponent> pairs with the General Purpose File Upload backend. As such, most configuration and state management decisions have been made for you and are baked-in. If you require a more flexible file upload input you may need to consider building your own.