File Upload

The File Upload component allows users to select and upload files via click-to-browse or drag & drop. It supports three layout variants — a general-purpose drag zone, an image-specific uploader, and a profile photo uploader — along with built-in validation for file size, file type, and maximum file count. Upload progress is simulated with a visual progress bar, and files can be cancelled or retried on failure.

Usage

Loading Code Block...

Full example

The default configuration renders a drag & drop zone that accepts a single file of any type, with a 5 MB size limit.

Loading Code Block...

Variants

Three layout variants are available via the variant prop.

Variant	Description
drag	General-purpose drop zone with file list, progress bars, and status icons.
image	Optimised for image uploads with a visual preview of the selected image.
profile	Circular avatar-style uploader for profile photos.

Disabled

Set disabled to prevent file selection and drag & drop interactions. The component receives reduced opacity and cursor-not-allowed.

File type restrictions

Use the accept prop to restrict which file types can be uploaded. The component provides predefined categories that map to MIME types and extensions:

Accept value	Allowed extensions
"all"	Any file type
"image"	.jpg, .jpeg, .svg, .png, .gif, .webp
"document"	.doc, .docx, .xls, .xlsx, .ppt, .pptx
"pdf"	.pdf
"video"	.mp4, .mov, .avi, .mkv, .webm

Multiple files

Enable multi-file uploads with the multiple prop. Use maxFiles to cap the number of files allowed.

Loading Code Block...

Upload lifecycle

The drag variant includes a full upload lifecycle with visual feedback:

1. User selects or drops files
             ↓
2. Validation (file size, file type, max count)
             ↓
       ┌─── PASS ───┐   ┌─── FAIL ───┐
       ↓             ↓   ↓             ↓
3. Progress bar       4. Error state
   animates              (red border,
       ↓                  retry icon)
       ↓                      ↓
5. Completed          6. Retry or
   (green ✓)             Remove

• Progress: Simulated upload progress with a progress bar and file size indicator.
• Success: Green border, check icon, “Completed” label.
• Error: Red border, alert icon, error message, with retry and delete options.
• Cancel: In-progress uploads can be cancelled by clicking the close icon.

---

FileUpload

Accessibility

• The file input is hidden visually and triggered programmatically by clicking the drop zone label.
• The drop zone is keyboard-accessible — users can tab to it and press Enter or Space to open the file picker.
• Error messages are displayed inline with alert icons for visual clarity.
• When disabled, pointer-events: none prevents accidental interaction.
• File status (uploading, completed, error) is communicated with both icons and text labels for users who cannot perceive colour alone.

Best practices

File size limits

Always enable displayFileSizeInfo when the file size limit is less than 5 MB, so users know the constraint before selecting a file.

Accept types

Use specific accept values rather than "all" whenever possible. This prevents users from selecting unsupported files and provides a better native file picker experience.

Multiple uploads

When using multiple, set a reasonable maxFiles value. The component will display an error message if the user tries to exceed the limit.

Upload simulation

The built-in progress animation simulates upload progress client-side. In production, replace the simulation with actual upload logic by handling the onFileUpload callback and updating progress from your API layer.