Multiple file upload

A multiple file upload component allows users to select and upload multiple files to a specific location.

Multiple file upload is able to:

Accept one or more files via browse or drag-and-drop
Provide their data to you using file objects via the onFileDrop callback prop
Read files as dataURLs, calling provided callbacks as needed when files start/finish being read, as well as when the read succeeds or fails
Display (in real time) the upload progress/status of each file
- Uploaded files are represented by the multiple file upload status item component, this component includes the aforementioned built-in file reading logic
- If you prefer to supply your own file reading logic and strictly use multiple file upload status item as a display component, the customFileHandler, fileName, fileSize, progressValue, and progressVariant props exist to allow you to do that

Restricting file size and type

As with singular file upload, any props accepted by react-dropzone's Dropzone component can be passed as a dropzoneProps object in order to customize the behavior of the Dropzone, such as restricting the type of files allowed. The following examples will only accept the files they list as accepted. Note that file type determination is not reliable across platforms (see the note on react-dropzone's docs about the accept prop), so be sure to test the behavior of your file upload restriction on all browsers and operating systems targeted by your application.

IMPORTANT: A note about security

Restricting file sizes and types in this way is for user convenience only, and it cannot prevent a malicious user from submitting anything to your server. As with any user input, your application should also validate, sanitize and/or reject restricted files on the server side.

Composable structure

File upload - multiple is designed in a composable manner to make customization easier. The standard sub-component relationships are arranged as follows:

<MultipleFileUpload>
  <MultipleFileUploadMain />
  <MultipleFileUploadStatus>
    <MultipleFileUploadStatusItem />
  </MultipleFileUploadStatus>
</MultipleFileUpload>

Examples

Basic

The below example demonstrates a typical application of file upload - multiple, with a few tweaks from that typical application to enhance the convenience of the example.

The "Show as horizontal" checkbox can be used to easily toggle the isHorizontal prop, showing our available styling variations.

The "Demonstrate error reporting by forcing uploads to fail" checkbox shows how our progressHelperText prop can be used to provide status messages to users, such as when a file fails to upload. While this checkbox is checked it will cause any file uploaded to automatically fail the file reading process, and helper text will be dynamically rendered which informs the user of that error.

Drag and drop files here

Accepted file types: JPEG, Doc, PDF, PNG

Show as horizontal

Demonstrate error reporting by forcing uploads to fail

Types

Multiple file upload uses the DropzoneOptions type from react-dropzone. It is comprised of additional props with their own types. For more information on using DropzoneOptions visit react-dropzone props and methods.

Additionally, it calls the onFileDrop callback with an event of type DropEvent. DropEvent is a union comprised of the following types:

React.DragEvent<HTMLElement>
 | React.ChangeEvent<HTMLInputElement>
 | DragEvent
 | Event

Props

MultipleFileUpload

Acts as a container for all other MultipleFileUpload sub-components. This sub-component also provides the functionality for file uploads, and access to the uploaded files via a callback.
*required
Name	Type	Default	Description
children	React.ReactNode		Content rendered inside the multi upload field
className	string		Class to add to outer div
dropzoneProps	DropzoneOptions	{}	Optional extra props to customize react-dropzone.
isHorizontal	boolean		Flag setting the component to horizontal styling mode
onFileDrop	(event: DropEvent, data: File[]) => void	() => {}	When files are dropped or uploaded this callback will be called with all accepted files

MultipleFileUploadMain

Creates the visual upload interface, including the area to drag and drop files, an optional upload button, and descriptive instructions.
*required
Name	Type	Default	Description
browseButtonText	string	'Upload'	Visible text label for the upload button
className	string		Class to add to outer div
infoText	React.ReactNode		Content rendered inside the info div
isUploadButtonHidden	boolean		Flag to prevent the upload button from being rendered
titleIcon	React.ReactNode		Content rendered inside the title icon div
titleText	React.ReactNode		Content rendered inside the title text div
titleTextSeparator	React.ReactNode		Content rendered inside the title text separator div

MultipleFileUploadStatus

Acts as an expandable container for all uploaded file statuses. An optional text and/or icon can also be passed into this sub-component. This sub-component can be conditionally rendered when at least 1 file has been attempted to be uploaded.
*required
Name	Type	Description
aria-label	string	Adds an accessible label to the list of status items.
children	React.ReactNode	Content rendered inside multi file upload status list
className	string	Class to add to outer div
statusToggleIcon	'danger' \| 'success' \| 'inProgress' \| React.ReactNode	Icon to show in the status toggle
statusToggleText	string	String to show in the status toggle

MultipleFileUploadStatusItem

Automatically reads an uploaded file to render a visual representation of it, including its name, size, and read status. This sub-component also allows custom reading of files via various callbacks which will override the automatic reading behavior.
*required
Name	Type	Default	Description
buttonAriaLabel	string	'Remove from list'	Adds accessibility text to the status item deletion button
className	string		Class to add to outer div
customFileHandler	(file: File) => void		A callback to process file reading in a custom way
file	File		The file object being represented by the status item
fileIcon	React.ReactNode		A custom icon to show in place of the generic file icon
fileName	string		A custom name to display for the file rather than using built in functionality to auto-fill it
fileSize	number		A custom file size to display for the file rather than using built in functionality to auto-fill it
onClearClick	React.MouseEventHandler<HTMLButtonElement>	() => {}	Clear button was clicked
onReadFail	(error: DOMException, onReadFail: File) => void	() => {}	A callback for when the FileReader API fails
onReadFinished	(fileHandle: File) => void	() => {}	A callback for when a selected file finishes loading
onReadStarted	(fileHandle: File) => void	() => {}	A callback for when a selected file starts loading
onReadSuccess	(data: string, file: File) => void	() => {}	A callback for when the FileReader successfully reads the file
progressAriaLabel	string		Adds accessible text to the progress bar. Required when title not used and there is not any label associated with the progress bar
progressAriaLabelledBy	string		Associates the progress bar with it's label for accessibility purposes. Required when title not used
progressAriaLiveMessage	string \| ((loadPercentage: number) => string)		Modifies the text announced by assistive technologies when the progress bar updates.
progressHelperText	React.ReactNode		Additional content related to the status item.
progressId	string		Unique identifier for progress. Generated if not specified.
progressValue	number		A custom value to display for the progress component rather than using built in functionality to auto-fill it
progressVariant	'danger' \| 'success' \| 'warning'		A custom variant to apply to the progress component rather than using built in functionality to auto-fill it

CSS variables

Expand or collapse column	Selector	Variable	Value

View source on GitHub