File field

Contract

The field itself is not hidden by display: none but taken away by a clip (clip-path) at a size of 1×1: a field hidden through display or visibility falls out of the order of traversal, and the zone stops being reachable from the keyboard.

The dashes are the one place in the library where a line is not solid, and that is deliberate: there is no other sign of "something can be put here" as understandable as this.

Inside the zone is a native input[type=file]: the system dialog, the filter by accept and the part in a form come from the platform. The field lies in a clip rather than being hidden — display: none would throw it out of the traversal. Tab puts the focus on the zone, Enter and Space open the dialog, and the ring is drawn around the whole zone rather than around the invisible 1×1 field.

The name is given by the call to action inside the <label>; the hint about the format is read next, because it too is inside.

Dragging is not the only way, and that is the point: by mouse, by keyboard and through the system dialog the zone is equally reachable. Uploading only by dragging is unavailable to almost everybody but a mouse. The zone itself is recognised by the dashes and the glyph rather than by the colour of the border, and a message about a wrong format is given as text beside it (a note or a banner).

States

<label class="inst-file">
  <input type="file">
  Drag a file in or choose one
  <span class="inst-file-hint">Up to 20 MB</span>
</label>
<label class="inst-file">
  <input type="file" disabled>
  Import is switched off by the administrator
  <span class="inst-file-hint">Speak to the owner of the space</span>
</label>

There is no "a file is over the zone" state in the library: it arises only from a drag event, that is, from JS. The application hangs a class of its own and paints with it the same two variables :hover uses.

Behavior

For the progress of an upload take a meter, for a report of an error a banner or a note.

JS

Include the module once per page — there is no need to initialise the components one by one, instrument.js works by delegation and sees nodes that arrived later.

<script type="module" src="instrument.js"></script>

What instrument.js does

Nothing. The zone draws the state of dragging but does not know what counts as an acceptable file — and without that, accepting files would be a promise the library cannot keep.

Without a script the zone works: inside it is a real <input type="file">, and choosing through the dialog is available by mouse and by keyboard alike.

What the application has to do

for (const type of ['dragenter', 'dragover']) {
  zone.addEventListener(type, (e) => {
    e.preventDefault();          // without this the browser opens the file itself
    zone.dataset.over = '';
  });
}
for (const type of ['dragleave', 'drop']) {
  zone.addEventListener(type, () => delete zone.dataset.over);
}

zone.addEventListener('drop', (e) => {
  e.preventDefault();
  input.files = e.dataTransfer.files; // the same path as the dialog's
  input.dispatchEvent(new Event('change', { bubbles: true }));
});

What was dragged in is put into the same <input>. A separate list would give the form two sources of files, and they would part on the very first submission.

Composition

In a form with a label

<div class="inst-field">
  <span class="inst-label">Import a list of recipients</span>
  <label class="inst-file">
    <input type="file" multiple accept=".json,.csv">
    Drag files in or choose them
    <span class="inst-file-hint">Up to 20 MB, the formats .json and .csv</span>
  </label>
</div>

The label here is a <span class="inst-label"> rather than a <label for>: the wrapper of the zone is a <label> itself, and a second label on the same field would give two competing names.

Patterns

With a report of the upload

<div class="inst-field">
  <span class="inst-label">Dataset</span>
  <label class="inst-file">
    <input type="file" accept=".csv">
    Drag a file in or choose one
    <span class="inst-file-hint">CSV, up to 100 MB</span>
  </label>
  <div class="inst-meter-row"><span>terrain.csv</span><span class="inst-meter-value">62%</span></div>
  <div class="inst-meter" role="progressbar" aria-label="Uploading terrain.csv"
       aria-valuenow="62" aria-valuemin="0" aria-valuemax="100">
    <div class="inst-meter-fill" style="inline-size:62%"></div>
  </div>
</div>

API

Related

Text fieldForm