Build Assets
UI Component
File Upload
Drag-and-drop + click file selection with progress, validation, and error states.
Platform: bothTags: file-upload, drag-drop, file, upload, attachment
Purpose
Lets users select and upload one or more files. Drag-and-drop reduces friction for power users; the click fallback ensures accessibility. Always show validation constraints upfront (file type, max size).
Anatomy
- Drop zone: dashed border rect, icon + primary instruction text
- Click trigger: "or click to browse" link inside the zone
- Constraints: file types and max size shown inside zone (13px tertiary)
- File preview row: filename, size, type icon, remove ×
- Progress bar: per-file upload progress
- Error state: red border, error message per file
States
- Idle: dashed border, grey icon, instruction text
- Drag over: solid accent border, light accent background
- File selected: file preview rows below zone
- Uploading: progress bar per file
- Upload complete: checkmark, success color
- Error: red border, error message ("File too large — max 10MB")
Tokens
spacing
zonePadding: 32px 24pxborderRadius: 12pxfileRowPadding: 10px 12px
Do
- Show accepted file types and max size before upload, not just on error
- Allow multiple file selection when multiple are valid
- Show per-file progress for uploads over 1 second
- Provide a remove button for each selected file before and during upload
Don't
- Silently reject invalid files — explain which files failed and why
- Block the entire UI during upload — upload in the background
- Show only a generic "Upload failed" message without specifics
- Remove the drop zone after files are selected — allow adding more
Accessibility
- Underlying <input type="file"> must exist (visually hidden but accessible)
- Drop zone: role="button", tabindex="0", aria-label="Upload files"
- Drag events: keyboard equivalent click must work identically
- Progress: aria-valuenow updates, announced via aria-live on completion/error