File uploads have a small number of requirements that must all be right, and getting one wrong produces a silent failure rather than an error. It is worth knowing all of them before debugging.
The three requirements
A file upload needs a file input, a POST method, and multipart encoding on the form. Miss the last and the server receives the filename as a plain string instead of the file.
<form action="/upload/" method="post" enctype="multipart/form-data"> <label for="avatar">Profile picture</label> <input type="file" id="avatar" name="avatar" accept="image/*"> <button type="submit">Upload</button> </form> Nothing warns you about the encoding. The form submits, the server receives a value, and the value is a short string where a document should be. This is the single most common file upload bug.
The accept attribute
The accept attribute filters which files the picker offers, taking a list of file extensions or media types.
accept="image/png, image/jpeg" accept=".pdf,.doc,.docx" accept="image/*" The wildcard forms cover whole categories of image, audio or video. On mobile, an image type frequently prompts the operating system to offer the camera as well as the photo library, which is a useful side effect.
Treat it strictly as a convenience. It filters a dialogue and does not enforce anything, since a user can usually switch the picker to show all files, and a request can be sent without any picker at all.
Multiple files
The multiple attribute allows several files to be chosen at once. Server languages generally need the field name written with brackets appended to receive them as a collection, which is a convention of those languages rather than of HTML.
Styling the control
The native file input is notoriously resistant to styling, with the button rendered by the browser in a way that varies between them.
The established approach hides the input visually and uses a label as the visible control, since clicking a label activates its associated input. Hide it with the visually hidden technique rather than display none, so it remains focusable and reachable by keyboard.
Whatever you build must show which file was chosen. The native control displays the filename, and a custom version that omits it leaves the user unsure whether their selection registered.
Drag and drop
Dropping files onto a region is a pleasant enhancement and must not be the only route. It requires a pointing device, precise motor control, and awareness that the region accepts drops.
Always keep a real file input available alongside it. The drop zone is an addition for those who want it, not a replacement for the control that works for everyone.
Size limits
HTML has no attribute for limiting file size. It can be checked in JavaScript before submission, which is a courtesy that avoids a long upload ending in rejection, and it is not enforcement.
The real limits are on the server, and there are usually several: a maximum upload size, a maximum post size, a request timeout, and possibly a limit in a proxy in front of the application. All must be configured consistently, and exceeding one often produces an unhelpful generic error, so testing with a genuinely large file is worthwhile.
Never trust an uploaded file
This is the part that matters. The filename, the reported media type and the extension all come from the client and can all be anything.
Validate the actual content on the server by inspecting the file rather than its name. Generate your own filename instead of using the one supplied, since a crafted name can attempt to escape the intended directory. Store uploads outside the web root, or in a location configured not to execute anything, so a file that turns out to be a script cannot be run by requesting it. Scan anything that will be shared with other users.
An upload endpoint is one of the most attractive targets on a site, because it accepts arbitrary data from strangers by design. Treating every uploaded file as hostile until proven otherwise is the only sound posture.
Reading files before upload
JavaScript can inspect a chosen file before anything is sent, which allows a preview thumbnail, a size check and a quick look at the file type. This improves the experience considerably, since a user who selected the wrong image finds out immediately rather than after a slow upload.
Client side image resizing is possible too, and on a form accepting photographs from phones it can reduce a multi-megabyte file to a fraction of its size before it leaves the device. As always, the server still validates whatever arrives.
Progress and feedback
A traditional form submission gives no indication of progress, so a large upload appears to hang. Sending the file in the background with a script allows a progress indicator and a cancel option, which for anything larger than a few megabytes is close to essential.