Form inputs

File upload queue

<forma-file-upload>

Native file selection plus a reusable upload queue for progress, success, cancellation, failure, and unknown outcomes.

Authoring tag
<forma-file-upload>
Category
Form inputs
Behavior owner
Native HTML / Limen
Canonical source
patterns/file-upload.html

Purpose

A file upload has two parts. The drop area holds a heading, guidance and a label.forma-button wrapping a native input type="file", so choosing files works with keyboard, pointer and touch without script. The queue is a list with one row per file: name and size, a native progress element, and either a Status lozenge outcome or a per-file action (Cancel, Retry). Uploading, progress updates, cancellation, retry, drag-and-drop and duplicate detection are Limen/application behavior; Forma renders each state the application reports.

Use when

  • Users attach one or more files to a record, submission or evidence set.
  • Uploads take long enough that per-file progress and outcomes matter.
  • Some files can fail or end in an unknown state and must be recoverable individually.

Avoid when

  • The user attaches files while writing a message to an agent or person: use Composer.
  • The upload is a single small file submitted with an ordinary form: a native file input with a Text field-style label is enough, without the queue.
  • The work is a long-running job rather than file transfer: use Operation status or Progress bar.

Behavior to know

  • Choosing files never depends on drag-and-drop; a drop target is an optional enhancement.
  • Each outcome has text (Uploaded, Failed, Outcome unknown) with a glyph, not only color.
  • Unknown outcome is distinct from failure: the application could not confirm what happened.

Basic example

The smallest correct markup: the canonical pattern from patterns/file-upload.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal file upload queue

Rendered from the canonical pattern file.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Add evidence files

Choose files. Drag and drop may be provided as an optional enhancement.

  • survey-results.csv1.8 MB
    100% Uploaded
  • evidence.pdf4.2 MB
    64%
HTML · Minimal file upload queue Raw HTML for HTML · Minimal file upload queue
<forma-file-upload class="forma-component-tag">
<section class="forma-file-upload" aria-labelledby="upload-title">
  <div class="forma-file-upload__drop">
    <h3 id="upload-title">Add evidence files</h3>
    <p>Choose files. Drag and drop may be provided as an optional enhancement.</p>
    <label class="forma-button">Choose files <input type="file" multiple></label>
  </div>
  <ul class="forma-file-upload__queue">
    <li>
      <div><strong>survey-results.csv</strong><small>1.8 MB</small></div>
      <progress value="100" max="100" aria-label="survey-results.csv upload progress">100%</progress>
      <span class="forma-status-lozenge" data-state="ok">Uploaded</span>
    </li>
    <li>
      <div><strong>evidence.pdf</strong><small>4.2 MB</small></div>
      <progress value="64" max="100" aria-label="evidence.pdf upload progress">64%</progress>
      <button type="button">Cancel</button>
    </li>
  </ul>
</section>
</forma-file-upload>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Failed, unknown and waiting files

A queue after a network interruption: one file was rejected for size (Failed lozenge with the reason), one lost its connection mid-transfer so the outcome is unknown and offers Check status, one is waiting (an indeterminate progress element with no value), and one failed on the server and offers Retry.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Attach contract documents

PDF or DOCX, up to 25 MB each.

  • master-agreement.pdfFailed: the file is larger than 25 MB (31.4 MB).
    0% Failed
  • schedule-b.docxConnection lost at 82%. We could not confirm whether the file was saved.
    82%
  • signatures.pdfWaiting to upload
    Waiting
  • pricing-appendix.pdfUpload failed: the server did not respond.
    40%
HTML · Failed, unknown and waiting files Raw HTML for HTML · Failed, unknown and waiting files
<forma-file-upload class="forma-component-tag">
  <section class="forma-file-upload" aria-labelledby="file-upload-mixed-title">
    <div class="forma-file-upload__drop">
      <h3 id="file-upload-mixed-title">Attach contract documents</h3>
      <p>PDF or DOCX, up to 25 MB each.</p>
      <label class="forma-button">Choose files <input type="file" name="contract-documents" multiple accept=".pdf,.docx"></label>
    </div>
    <ul class="forma-file-upload__queue">
      <li>
        <div><strong>master-agreement.pdf</strong><small>Failed: the file is larger than 25 MB (31.4 MB).</small></div>
        <progress value="0" max="100" aria-label="master-agreement.pdf upload progress">0%</progress>
        <span class="forma-status-lozenge" data-state="blocked">Failed</span>
      </li>
      <li>
        <div><strong>schedule-b.docx</strong><small>Connection lost at 82%. We could not confirm whether the file was saved.</small></div>
        <progress value="82" max="100" aria-label="schedule-b.docx upload progress">82%</progress>
        <button type="button">Check status</button>
      </li>
      <li>
        <div><strong>signatures.pdf</strong><small>Waiting to upload</small></div>
        <progress max="100" aria-label="signatures.pdf upload progress">Waiting</progress>
        <button type="button">Remove</button>
      </li>
      <li>
        <div><strong>pricing-appendix.pdf</strong><small>Upload failed: the server did not respond.</small></div>
        <progress value="40" max="100" aria-label="pricing-appendix.pdf upload progress">40%</progress>
        <button type="button">Retry</button>
      </li>
    </ul>
  </section>
</forma-file-upload>

Click or tap the code once to select all of it, then copy.

Scenario

Single profile photo

Single-file mode: no multiple attribute and an image-only accept filter. The queue shows the one uploaded file with a Replace path through the same chooser.

Profile photo

A square PNG or JPEG works best. Choosing a new file replaces the current one.

  • headshot-2026.jpg640 KB
    100% Uploaded
HTML · Single profile photo Raw HTML for HTML · Single profile photo
<forma-file-upload class="forma-component-tag">
  <section class="forma-file-upload" aria-labelledby="file-upload-single-title">
    <div class="forma-file-upload__drop">
      <h3 id="file-upload-single-title">Profile photo</h3>
      <p>A square PNG or JPEG works best. Choosing a new file replaces the current one.</p>
      <label class="forma-button">Choose photo <input type="file" name="profile-photo" accept="image/png,image/jpeg"></label>
    </div>
    <ul class="forma-file-upload__queue">
      <li>
        <div><strong>headshot-2026.jpg</strong><small>640 KB</small></div>
        <progress value="100" max="100" aria-label="headshot-2026.jpg upload progress">100%</progress>
        <span class="forma-status-lozenge" data-state="ok">Uploaded</span>
      </li>
    </ul>
  </section>
</forma-file-upload>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile evidence upload

An evidence queue at phone width. Queue rows stack their parts and actions become full-width buttons.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • At 40rem (640px) and below each queue row becomes one column: file name and size, then the progress bar, then the status or a full-width action button.
  • The Choose files button keeps a 44px minimum height; on phones it opens the platform chooser, which may offer the camera or photo library.
  • Long file names wrap within the row instead of widening the queue.
  • The drop area has no drag requirement, so touch users lose nothing.
HTML · Mobile evidence upload Raw HTML for HTML · Mobile evidence upload
<forma-file-upload class="forma-component-tag">
  <section class="forma-file-upload" aria-labelledby="file-upload-mobile-title">
    <div class="forma-file-upload__drop">
      <h3 id="file-upload-mobile-title">Add site photos</h3>
      <p>Photos of the installed equipment and serial plates.</p>
      <label class="forma-button">Choose files <input type="file" name="site-photos" multiple accept="image/*"></label>
    </div>
    <ul class="forma-file-upload__queue">
      <li>
        <div><strong>rack-07-front-panel-serial-plate.jpg</strong><small>3.1 MB</small></div>
        <progress value="100" max="100" aria-label="rack-07-front-panel-serial-plate.jpg upload progress">100%</progress>
        <span class="forma-status-lozenge" data-state="ok">Uploaded</span>
      </li>
      <li>
        <div><strong>rack-07-cabling.jpg</strong><small>2.4 MB</small></div>
        <progress value="35" max="100" aria-label="rack-07-cabling.jpg upload progress">35%</progress>
        <button type="button">Cancel</button>
      </li>
    </ul>
  </section>
</forma-file-upload>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
typeinput / buttonfile on the chooser; button on queue actions—The native file chooser; queue actions are type=button so they never submit a form.
multipleinput[type=file]booleanabsentAllows selecting several files at once.
acceptinput[type=file]extensions or MIME typesanyFilters the chooser. It is a hint, not enforcement: the application must still validate type and size.
nameinput[type=file]string—Field name when the files are submitted with a form.
aria-labelledbysection.forma-file-uploadid of the heading—Names the upload region with its visible heading.
valueprogressnumberabsent (indeterminate)Current progress. Omit it for waiting or unknown-size transfers.
maxprogressnumber1Scale of the progress value.
aria-labelprogressstring—Names each progress bar with its file so rows are distinguishable.
data-state.forma-status-lozengeok | attention | unknown | blocked—Outcome glyph for the file's status lozenge; always paired with text.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-file-uploadBlock class—Root grid (1rem gap) around the drop area and queue.
.forma-file-upload__dropElement class—Dashed-border selection area on the secondary surface. A .forma-button inside is the visible chooser; a nested input[type=file] is visually hidden but remains in the accessibility tree.
.forma-file-upload__queueElement class—Unstyled list of files. Each li is a three-column grid (name and size, progress, status or action) that stacks at 40rem and below; small holds secondary text.
Keyboard interaction
KeysResult
TabMoves to the file input inside the Choose files label, then through queue action buttons in order.
Enter / SpaceOpens the native file chooser from the focused file input, or activates a queue action.
Events
EventDescription
changeNative event from the file input after the user picks files. Uploading, progress and outcomes are application code; Forma adds no events.

Form behavior

The file input submits the chosen files under name with a multipart form. A queue that uploads immediately is application behavior outside native form submission.

States

File upload queue states
StateHow it is expressedPresentation
Waitingprogress without valueIndeterminate progress bar and "Waiting" text; a Remove action is usual.
Uploadingprogress value < maxDeterminate bar with a Cancel action.
Uploadedprogress value = max; .forma-status-lozenge data-state="ok"Full bar and a ✓ Uploaded lozenge.
Failed.forma-status-lozenge data-state="blocked" or a Retry button, plus a reason in smallThe reason is text; retry is offered when the failure is recoverable.
Unknown outcomeapplication text plus a Check status action or data-state="unknown" lozengeKept distinct from failure because the file may have been saved.

Accessibility

Forma provides

  • The chooser is a real file input inside a visible button-styled label, so it works by keyboard, pointer and touch with no drag requirement.
  • Queue outcomes combine text and a glyph through Status lozenge, never color alone.
  • Queue rows stack at narrow widths and action buttons become full width.

Your application supplies

  • Give each progress element an accessible name that includes the file name.
  • Announce completed, failed and unknown outcomes (for example with a polite live region or Toast), without announcing every progress tick.
  • Validate type and size in the application and explain rejections in the row text.
  • Verify that keyboard focus on the visually hidden file input is visible; Forma does not currently draw a focus indicator on the Choose files label.
  • When adding a drop zone, keep the Choose files path and announce files added by drop.

Responsive behavior

  • Above 40rem each row is minmax(0, 1fr) minmax(8rem, 0.5fr) auto: the name column shrinks first and the progress bar keeps at least 8rem.
  • At 40rem (640px) and below rows become one column and queue buttons fill the width.
  • File names and reasons wrap inside the first column; the queue never scrolls horizontally.

Motion

  • No animation of its own: Forma does not animate queue rows or outcomes. The native progress bar's indeterminate animation, where the platform draws one, is browser-owned; the Choose files button and queue buttons use the shared hover and press background interpolation.

Usage guidance

Do

  • State accepted types and size limits before the user chooses files.
  • Offer Cancel while uploading and Retry after recoverable failures, per file.

Avoid

  • Reporting an interrupted upload as failed when the server may have saved it; show an unknown outcome and a way to check.
  • Making drag-and-drop the only way to add files.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.