Components · Inputs
File Upload
A drop zone plus a file dialog. Three states — ready, uploading, and the list of what has been attached — with the limits stated before the user picks anything.
Figma source: File Upload ↗Examples
Drop zone — drag a file over it to see the active state
Attachments
Drop files here
or
Add up to nine attachments per task. 75 MB per file. .exe files cannot be accepted.
<div class="cds-dropzone" aria-labelledby="fu-label">
<strong>Drop files here</strong>
<span>or</span>
<button type="button" class="cds-button cds-button--secondary">Choose files</button>
</div>
<span class="cds-field__caption">
Add up to nine attachments per task. 75 MB per file. .exe files cannot be accepted.
</span>Uploading, and a failed upload
Uploading 2 files…
budget-fy26.xlsx · 4.2 MB
Figma properties
| Property | Values | Notes |
|---|---|---|
State | Default · Ready · Uploading | Resting, file selected and ready, and in progress. |
Sizing rules from the Figma annotations:
- Minimum width 220px. Below that the drop target is too small to aim at.
- Inside an auto-layout parent, use Fill container — the drop zone should take the width available rather than sit at a fixed size.
- Allow generous space for the drop target; a thin strip is hard to hit and easy to miss.
Usage
The Figma page raises an open question about upload feedback — whether a delay is needed so users see that something happened, and whether the loading indicator should match the Flowable tile treatment. The answer that holds regardless:
When to use it
- State the limits — count, size, accepted types — before the user chooses a file.
- Show progress per file, not one bar for the batch, so a single slow file is identifiable.
- Report failures per file with the reason, as in the example above.
- Keep the successful files when some in a batch fail. Never discard the whole upload.
- Provide a file dialog button as well as the drop zone.
When not to use it
- Do not rely on drag and drop alone — it is unavailable to keyboard users and awkward on touch.
- Do not show a spinner with no text; “Uploading 2 files” tells the user what is happening.
- Do not silently reject a file. Say which file, and why.
- Do not add an artificial delay purely so the spinner is visible — make the completion state unmistakable instead.
Drag and drop must never be the only route
WCAG 2.2 SC 2.5.7 Dragging Movements requires that anything achievable by dragging is also achievable with a single pointer action. The “Choose files” button satisfies this — which is why it is part of the component, not an optional extra.
Accessibility
- The underlying
<input type="file">stays in the DOM and keyboard reachable; the styled drop zone is a label for it. - Announce upload progress and completion through a polite live region.
- Announce failures through
role="alert"so they interrupt — a failed upload the user does not notice is a lost submission. - Each attached file needs a remove control with a name identifying the file.
Tokens consumed
| Token | Applied to | Resolves to |
|---|---|---|
--color-gray-100 | Drop zone fill | #f5f5f5 |
--color-gray-400 | Dashed border | #888c8c |
--primary-brand-color | Border and text while dragging or uploading | #0076b6 |
--color-blue-100 | Fill while dragging | #e1eaf8 |