File upload

​

When to use

• When users need to submit documents, images, or other media.
• In forms or workflows that require file attachments (e.g., profile pictures, reports, invoices).
• When multiple files need to be uploaded efficiently and with clear feedback.

​

When to use something else

• When an alternative method (e.g., selecting from a gallery, embedding links) is more efficient.
• For small text-based input: use an Input instead (e.g., entering a URL instead of uploading a document).
• If users will frequently reuse files, consider providing a file repository instead of requiring uploads each time.
• When real-time document collaboration is needed, opt for embedded editors instead.

​

Dos and don’ts

• Do explicitly list file size limits and allowed formats upfront.
• Do show explicit visual progress indicators for active uploads.
• Do provide clear visual dropzone highlighting when a user drags a file over the target.
• Do allow users to cancel or pause ongoing uploads.
• Do validate file extensions and size limits on the client side before network requests.
• Do provide inline validation feedback on file uploads.
• Don’t freeze or block the entire application UI during background transfers.
• Don’t rely solely on drag-and-drop interactions without an explicit “Browse” button.
• Don’t auto-dismiss upload completion or error banners before users read them.
• Don’t truncate long file names without showing the full string on hover.

​

Behavior

• Multi-file upload: If allowing multiple files to be uploaded, a list of uploaded files will appear below the File upload area. This ensures the user can still add more files later or remove specific files that are no longer needed.
• Single-file upload: If only one file is allowed to be uploaded, the File upload area is replaced by the uploaded file. This removes the possibility for the user to add additional files unless they remove the uploaded one.

​

Often used with

​

Accessibility

• Connect custom dropzones: Link custom visual dropzones to a native <input type="file">. Connect persistent helper text (for example file limits and formats) directly using aria-describedby.
• Open the file picker from keyboard: Ensure pressing Space or Enter on the dropzone or visual trigger opens the system file picker natively.
• Announce upload status: Wrap real-time progress, success notifications, and upload status changes in a container marked with aria-live="polite".
• Name removal controls: Give every removal control in a multi-file queue a unique, context-aware accessible name (for example aria-label="Remove invoice_2026.pdf").
• Preserve focus on delete: Direct focus to the removal button of the next file in the list, or back to the primary upload button, when a user deletes an uploaded item.
• Link validation errors: Flag validation failures with aria-invalid="true" and link inline error messages using aria-errormessage.