File input

File input lets users upload one or more files from their computer by browsing or dragging them into a drop zone.

#Example

#Usage

#Generic

#Images

#Credentials

#Multiple files

Set multiple to let users pick more than one file at a time. onFilesChange fires on every change to the selection (each addition, removal and clear), receiving the accepted files and the ones that were refused.

A selection renders above the drop zone, so users can review what they picked and remove anything they didn't mean to include. The drop zone stays on screen underneath as a slim bar, and a further drop adds to the selection. Removing the last file restores the full drop zone.

A caption above the list shows how many files are selected and their combined size, alongside a Clear all control once there are two or more. Adding a file already in the selection skips it silently, matching on name, size and last-modified date. The caption hides its count while any file is refused, since the group headers below carry their own counts.

onFilesChange fires only when the selection actually changes, so an add of nothing but duplicates, or one refused for exceeding maxFiles, does not call it. Multiple mode reports no upload progress: onFilesChange describes a selection, so a consumer doing slow work in it owns its own pending state.

#Per-file rejections

Setting accept filters the browse dialog to those extensions, but a drag & drop can still bring in anything. Files that fail validation are listed separately, under their own heading, with the reason shown beneath each name. The two headings default to "Valid files" and "Unable to upload"; override them with validFilesLabel and invalidFilesLabel to match the surrounding flow.

onFilesChange also receives the rejections as its second argument, so the surrounding UI can act on them. A rejection carries the original File, a reason of invalid-extension or file-too-large, and a message safe to display as-is. A file that fails both checks reports invalid-extension, since an unsupported file's size is beside the point.

#Clearing a selection

Clear all empties the accepted files and the refused ones together, and fires onFilesChange with two empty arrays. FileInput is uncontrolled and holds no history. A consumer that wants an undo affordance keeps the previous File[] in its own state and re-submits it through its own upload flow; there is no prop for pushing a selection back into the input.

#Limiting how many files

Use maxFiles to cap how many files the selection may hold in total. A drop that would carry the selection past the cap is refused whole: none of the incoming files are taken, and the drop zone shows the error inline. Only accepted files count toward the cap. maxFiles is unlimited when omitted, and is only available alongside multiple.

#Upload progress

Simulated upload progress is automatically shown when onUpload event handler returns a promise.

If onUpload takes less than 200ms to execute, upload progress won't be displayed.

#Error handling

When an uploaded file doesn't pass some additional validation, throw a FileUploadError with an error message that will be displayed in FileInput. Try uploading any file in the example below to see how it works. onFilesChange follows the same rule, so a multiple input can report a failure the same way, at any selection size.

When either handler throws any other error, FileInput shows a generic message and still surfaces the error to the window: onUpload rethrows it, so it arrives as an unhandled rejection, and onFilesChange passes it to reportError.

#Disabled

When user is not allowed to upload a file, FileInput can be disabled.

#Props

#FileInput

Inherits margin props.

Name	Default	Description
isDisabled	false	boolean Determines whether file input is disabled.
accept	—	string[] List of file extensions to accept in this file input.
maxSize	1000 * 1000 * 10 (10 megabytes)	number Maximum size of an individual file.
onUpload	—	(file: File) => Promise<void> | void Event handler when user has selected a file. Required unless `multiple` is set. Throw a `FileUploadError` to show your own message inline. Any other error shows a generic message and surfaces as an unhandled rejection.
multiple	false	false | true Determines whether more than one file can be selected at a time.
onFilesChange	—	( files: File[], rejections: FileRejection[], ) => Promise<void> | void Event handler for every change to the selection (each addition, removal and clear), receiving the accepted files and the ones refused, with why. Required when `multiple` is set. Throw a `FileUploadError` to show your own message inline. Any other error shows a generic message and is passed to `reportError`.
maxFiles	—	number Maximum number of files the selection may hold in total, counting accepted files only. Unlimited by default. Requires `multiple`.
validFilesLabel	—	string Heading above the accepted files once some were refused. Requires `multiple`.
invalidFilesLabel	—	string Heading above the refused files. Requires `multiple`.