Skip to content
Leonidov.DEV

File Upload Form: 5 Rules That Keep It Native

Engineering
File Upload Form: 5 Rules That Keep It Native

Every form audit reaches the same field. The mockup shows a dashed rectangle, a paperclip icon and a pretty list; the implementation shows a grey “Choose file” button, and the argument starts about which one is “real”. The file upload form is the place where a design and the platform disagree most, and the cheapest resolution is to keep the platform and dress it.

Code: Oat-Upload, MIT licensed.

I built the widget as an extension for Oat UI rather than a library of its own, and five rules decided what it does. Each one came from a support ticket I have seen in someone else’s code.

Rule 1: the native input is the contract

An <input type="file"> carries name, accept, multiple and disabled, and the browser enforces them before any script runs. A widget that hides the input and posts a JavaScript array breaks that contract the moment a script fails.

So <ot-upload> wraps the field and leaves it in the form:

<ot-upload max-size="5242880" max-files="5">
  <input type="file" name="attachments" multiple accept="image/*,.pdf">
</ot-upload>

The server sees the same field it saw before the redesign. Nothing in the request changed, and that is the test I apply to every component: remove the script and the form must still submit.

Rule 2: the browser validates first, my limits second

accept and multiple belong to the platform, so the widget reads them there. Size and count are ours, because no browser enforces them for a plain file input.

The order matters in review. A component that checks accept with its own list of MIME types will reject files the browser accepts, and then the bug is a file that uploads on one machine and not on another.

Rule 3: a rejected file must not clear the selection

The most expensive mistake in this widget is resetting the input on error. A customer attaches eight scans, the ninth is over the limit, and everything disappears. They now believe the form is broken, and support receives a screenshot.

Here a rejected file is reported through ot-upload-error and never enters the list. The eight accepted files stay, the message names the reason, and the ninth can be replaced. reason is one of type, size, count or disabled, so the text can be specific instead of “invalid file”.

Rule 4: the progress number belongs to the network

setProgress() takes a number between 0 and 100 and writes it to a native <progress>. The widget does not animate anything and does not estimate.

A timer that pretends to load is a lie the user can see: the bar reaches 100 and the page sits there. A real number from the request code is honest, including the moment when it stops moving because the connection did.

Rule 5: removing a file is part of the form

remove() takes a file, an index or an item id, and where DataTransfer is available the widget writes the remaining files back into the input. Without that, the list on screen and the payload in the request disagree, and the server receives a file the user deleted.

That single detail is worth more than any visual polish: the preview and the request are the same state.

What the widget refuses to do

It does not upload. There is no endpoint in the package, no token, no retry policy. Chunked transfer, S3 signatures and virus scanning belong to the application, and a component that guesses at them becomes a framework nobody asked for.

It also does not offer a drag-only path. A <label for="files"> opens the picker on click and on Enter, so the drop zone is an enhancement over a control that already worked.

What this teaches about components

Write the component smaller than the problem. The five rules here are all about not taking responsibility away from the browser, and that is why the package stays at one stylesheet and one script with no runtime dependencies.

The same reasoning runs through progressive enhancement: a page with a working state before the script is easier to test and cheaper to keep. It is also the argument I make in building a php framework about a 2 MB core rather than a full stack.

Oat Upload is MIT and ships from npm as @globus.studio/oat-upload, with the source on GitHub.