Skip to content

Native File Input: 5 Parts of an Upload Widget

4 min read Notes

Native File Input: 5 Parts of an Upload Widget

A native file input does one thing well and stops there: it opens the picker and hands the browser a FileList. No preview, no removal, no size check before the request, no progress. A widget around it can stay small if it keeps that contract and adds only the missing parts. That is the shape of <ot-upload>.

Code: Oat-Upload, MIT licensed.

Five HTML parts make the widget, and every one of them is already in a normal form.

The input comes first

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

The custom element wraps the input it finds inside, so the name, multiple and accept stay where the browser reads them. Nothing is copied into a JavaScript data model until the user acts, and a form with JavaScript disabled posts the same field as before.

The five parts, when you want your own markup

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

  <label data-upload-dropzone for="files">
    <strong>Drop files here</strong>
    <small class="text-light">Images or PDF, up to 5 MB each.</small>
  </label>

  <output data-upload-error role="status" aria-live="polite"></output>
  <ul data-upload-list aria-label="Selected files"></ul>
  <progress data-upload-progress max="100" value="0" hidden></progress>
  <output data-upload-status aria-live="polite"></output>
</ot-upload>

Each hook is optional. Provide data-upload-list and the widget fills your list; omit it and the element builds one. The <label for="files"> opens the picker by itself, which keeps the drop zone keyboard accessible without a key handler.

Validation reads the browser first

The rule is that the native attributes win. accept, multiple and disabled behave exactly as the platform defines them, and max-size and max-files on <ot-upload> add the two checks the platform does not perform.

A rejected file never enters the list. It fires ot-upload-error with file, reason and message, and reason is one of type, size, count or disabled. That is enough for a form to say what happened without parsing a string:

upload.addEventListener('ot-upload-error', (event) => {
  console.log(event.detail.reason, event.detail.message);
});

One state, kept in sync

The accepted files live on the element and are exposed as files. addFiles() accepts a FileList or an array, remove() takes a File, an index or an item id, clear() empties the selection, and setProgress() drives the native <progress>.

Where DataTransfer exists, the widget writes the accepted files back into the input, so the preview list and the submitted payload cannot disagree. A remove() that only edits the DOM would leave the request carrying a file the user deleted, and that bug is common enough to be worth the explicit test.

ot-upload-change reports files, added, removed and rejected for the current operation, which is what a form needs to enable a submit button or to show a running total.

Progress without a fake bar

setProgress(65) sets value on <progress>; setProgress(null) or resetProgress() hides it. The widget does not upload anything, so the number comes from your request code (XHR progress, a chunked uploader, a fetch wrapper). That is a deliberate split: the component owns the UI state, the application owns the network, and neither guesses about the other.

What it costs a page

One stylesheet, one script, no runtime dependencies, and the markup in the example above if you write the parts yourself. The base is Oat UI, loaded from a CDN or bundled, and the extension adds the upload behaviour on top.

There is no server side in this package, and that is correct: size and type are a user experience check, not a security boundary. The server still validates the file it receives, still stores it outside the web root where it can, and still enforces its own limit.

Where the component ends

Chunked uploads, resumable transfers, direct-to-S3 signatures and virus scanning are application problems. <ot-upload> gives them the events and the progress element to report through, and stops before inventing an API for the network layer.

Related: semantic table for the same approach applied to <table>, and modular php framework for the server that usually receives these files.

Custom work

Need an API that does not exist yet?

Describe the task and the response format. We will estimate the endpoint, the integration and the maintenance.

Start a conversation