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.
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.
<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).
Failed
schedule-b.docxConnection lost at 82%. We could not confirm whether the file was saved.
signatures.pdfWaiting to upload
pricing-appendix.pdfUpload failed: the server did not respond.
<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.
<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.
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.
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.
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
Attribute
On
Values
Default
Description
type
input / button
file on the chooser; button on queue actions
—
The native file chooser; queue actions are type=button so they never submit a form.
multiple
input[type=file]
boolean
absent
Allows selecting several files at once.
accept
input[type=file]
extensions or MIME types
any
Filters the chooser. It is a hint, not enforcement: the application must still validate type and size.
name
input[type=file]
string
—
Field name when the files are submitted with a form.
aria-labelledby
section.forma-file-upload
id of the heading
—
Names the upload region with its visible heading.
value
progress
number
absent (indeterminate)
Current progress. Omit it for waiting or unknown-size transfers.
max
progress
number
1
Scale of the progress value.
aria-label
progress
string
—
Names each progress bar with its file so rows are distinguishable.
data-state
.forma-status-lozenge
ok | attention | unknown | blocked
—
Outcome glyph for the file's status lozenge; always paired with text.
CSS hooks (derived from dist/all.css)
Hook
Kind
Values or default
Description
.forma-file-upload
Block class
—
Root grid (1rem gap) around the drop area and queue.
.forma-file-upload__drop
Element 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__queue
Element 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
Keys
Result
Tab
Moves to the file input inside the Choose files label, then through queue action buttons in order.
Enter / Space
Opens the native file chooser from the focused file input, or activates a queue action.
Events
Event
Description
change
Native 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
State
How it is expressed
Presentation
Waiting
progress without value
Indeterminate progress bar and "Waiting" text; a Remove action is usual.
Uploading
progress value < max
Determinate bar with a Cancel action.
Uploaded
progress 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 small
The reason is text; retry is offered when the failure is recoverable.
Unknown outcome
application text plus a Check status action or data-state="unknown" lozenge
Kept 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.