File Upload
Last Updated: September 2026File uploads allow the user to upload a file from their local machine into the product. Dropzones allow the user to more flexibly transfer assets from their local system to the product surface.
Source CodeAnatomy
link- 1Dropzone
- 2Description
Variants
linkDropzone
Default. Full-width dashed area with browse link and optional description.
Button
Standalone Upload button that opens the system file picker.
Disabled
disabled prevents picking and dropping files.
With accept / multiple
Native input attributes pass through to the hidden file input.
Usage Guidelines
linkWhen to use
- •To let users attach documents or images to a form or workflow.
- •When drag-and-drop improves discoverability for multi-file uploads.
- •As a compact Upload action when space is limited (button variant).
When not to use
- •For single-line text entry — use Input or Select.
- •When files are already selected and need status UI — pair with FileList / FileElement.
- •For camera capture or media recording — use a dedicated media control.
State allowed types and size limits in description.
Don't leave users guessing which formats are accepted.
Use variant="button" when the upload sits among other compact controls.
Don't force the dropzone into dense toolbars — switch to the button variant.
Behaviors
linkFile selection
- •Click (or browse files) opens the system picker via a hidden type="file" input.
- •Dropzone accepts drag-and-drop; drag-over styles highlight the target.
- •onFiles receives File[] whenever files are chosen or dropped.
Input reset
- •After change, the input value is cleared so the same file can be selected again.
Disabled state
- •disabled blocks click, drag, and the picker.
- •Dropzone and button variants both respect disabled styling.
Content Guidelines
linkDescription
- •List accepted formats and a max size (e.g. 'PDF, PNG or JPG (max. 5mb)').
- •Keep description to one short line.
Labels
- •Dropzone copy is fixed: 'Drop files here or browse files'.
- •Button variant label is fixed: 'Upload'.
Accessibility
linkText & Labels
- •Dropzone uses aria-label="Drop files here or browse files".
- •Provide clear description text for accepted file types.
ARIA attributes
- •The interactive surface is a button that opens the file picker.
- •The file input is visually hidden but remains in the accessibility tree via id.
Keyboard Support
- •Tab → focus the dropzone button or Upload button.
- •Enter / Space → open the file picker.
WCAG Compliance Standards
FAQs
linkHow do I restrict file types?
Pass accept (and optionally multiple) — they forward to the hidden file input.
Where do selected files go?
Handle File[] in onFiles. Pair with FileList / FileElement for progress and removal UI.
Dropzone or button?
Use dropzone for primary attachment areas; use button when space is tight or upload is secondary.