React Reference ยท Built-in DOM Components
The input type file in React
Reference for the React file input: why it is always uncontrolled, reading event.target.files, accept and multiple, clearing it, previews and upload basics.
A file input, <input type="file">, lets the user pick files from their device. For security reasons a web page can never set the chosen file, so in React a file input is always uncontrolled: you cannot give it a value, and you read the selection from the DOM. The only string a script may assign to its value is the empty string, which clears it.
You use it through an onChange handler. The event's target.files is a FileList of File objects, each with a name, size, type and lastModified. From there you can validate, show a preview, or send the files with fetch and FormData.
<input type="file" accept="image/*" multiple onChange={(event) => handleFiles(Array.from(event.target.files))} />
Try it
Select a few files from your own computer. The files stay in the browser; this page does not upload them anywhere.
Assigning a path throws an InvalidStateError. This is the reason React cannot offer a controlled file input: there is nothing it could write into the field. A defaultValue fails the same way.
Syntax
<input type="file" accept=".pdf,image/*" multiple capture="environment" onChange={handler} />
function handler(event: React.ChangeEvent<HTMLInputElement>): void { const files: FileList | null = event.target.files; }
| Prop | Description |
|---|---|
type="file" |
Required. |
onChange |
Fires after the user confirms a selection. Read event.target.files. |
accept |
Comma-separated hints: extensions (.pdf) or MIME types (image/*). It filters the picker but is not validation. |
multiple |
Allow several files. Without it, files holds at most one. |
capture |
On phones, asks for the camera or microphone (user or environment). |
webkitdirectory |
Select a whole folder (widely supported, not standardized). Pass it as a lower-case attribute. |
name, required, disabled |
Work like on other inputs; with a name the files go into FormData. |
ref |
Use it to clear the input or to open the picker with ref.current.click(). |
Returns: a React element with no children.
Errors: value or defaultValue with a non-empty string throws InvalidStateError when React sets it on the DOM node.
Usage notes
- Never trust
accept,typeorsizealone. They come from the browser and the file name. Check type and size again on the server. - Clear the input with
event.target.value = ''orref.current.value = '', or give the input a newkeyto remount it. Without clearing, choosing the same file twice does not fireonChange. FileListis not an array. UseArray.from(files)before callingmaporfilter, and copy it into state, because the list belongs to the live input.- Previews:
URL.createObjectURL(file)gives a temporary address for an<img>. Release it withURL.revokeObjectURLin an effect cleanup so memory is not leaked. - Uploads: append files to a
FormDataandfetchit; do not set theContent-Typeheader yourself, so the browser adds the multipart boundary. - Form actions: inside
<form action={fn}>the action receivesFormDatacontaining theFileobjects. - Hiding the native control is fine for styling: put the input in a
<label>styled as a button, or callclick()on it from a real<button>. Keep it focusable. - The sandboxed demo here can pick local files but cannot upload to a server.
- Large files should be streamed or sliced (
file.slice) instead of read whole into memory.