file-input

File Input

Upload and handle files

What it solves

A File Input is a form component that allows users to select one or more files from their device's file system and upload them to a server. It ranges from the native <input type="file"> control to enhanced drop zones with drag-and-drop, file previews, upload progress indicators, and validation feedback. File inputs appear in document management, profile photo upload, e-commerce product imagery, form attachment flows, and media-rich applications.

When to use

• Profile and avatar upload – Users select a photo for their account.
• Document submission – Forms that require attached PDFs, contracts, or ID documents.
• Media uploads – Images or videos for social media, e-commerce listings, or galleries.
• Bulk import – CSV or JSON files for data import workflows.
• Email attachments – Web mail applications.

When to avoid

• Camera capture on mobile – Use <input type="file" capture="environment"> or capture="user" to open the camera directly.
• Cloud file selection – Google Drive or Dropbox pickers require their own SDKs.
• Very large files – Consider chunked upload APIs rather than a standard form file input.
• Real-time streaming content – Not appropriate for live audio/video streams.

Implementation workflow

1. Confirm the pattern matches the problem and constraints before copying the example.
2. Start from the anatomy and examples in references/pattern.md, then choose the smallest viable variation.
3. Apply accessibility, performance, and interaction guardrails before layering visual polish.
4. Use the testing guidance to verify behavior across keyboard, screen reader, responsive, and failure scenarios.

Accessibility guardrails

Keyboard Interaction Pattern

Performance guardrails

• File selection dialog open: < 100ms from click to dialog appearance
• File preview generation: < 200ms for image thumbnails (up to 5 MB)
• Client-side validation: < 50ms per file
• Progress bar update: < 16ms per frame (smooth animation)
• Memory usage: < 50KB per file input component; image preview memory managed with URL.revokeObjectURL()

Common mistakes

Client-Side Validation Only

The Problem: Validating file type by extension only on the client allows users (or malicious actors) to rename files and bypass restrictions.

How to Fix It? Validate both client-side (for UX) and server-side (for security).

// Client-side check (UX only)
function isValidFileType(file, accept) {
  return accept.split(',').some(type => {
    type = type.trim();
    if (type.startsWith('.')) return file.name.endsWith(type);
    if (type.endsWith('/*')) return file.type.startsWith(type.slice(0, -1));
    return file.type === type;
  });
}

# Server-side check (security-critical) — Python example

allowed_types = ['image/jpeg', 'image/png', 'application/pdf']
mime_type = magic.from_buffer(file_bytes, mime=True)
if mime_type not in allowed_types:
    raise ValueError("Invalid file type")

No Upload Feedback for Large Files

The Problem: Users submit a form, see nothing happen for 30 seconds, and assume it is broken. They click submit again, causing duplicate uploads.

How to Fix It? Always show upload progress for uploads that will take more than 1 second.

const xhr = new XMLHttpRequest();
xhr.upload.addEventListener('progress', (e) => {
  if (e.lengthComputable) {
    const percent = Math.round((e.loaded / e.total) * 100);
    progressBar.setAttribute('aria-valuenow', percent);
    progressBar.style.width = `${percent}%`;
    progressText.textContent = `${percent}%`;
  }
});

Not Handling Drop Zone Keyboard Access

The Problem: A drop zone implemented as a <div> is not keyboard-accessible, excluding users who cannot use a mouse.

How to Fix It? Make the drop zone keyboard operable.

<!-- Good: keyboard-accessible drop zone -->
<div
  class="file-input__dropzone"
  role="button"
  tabindex="0"
  aria-label="Upload files. Press Enter or Space to open file browser."
>
  <!-- ... -->
</div>

dropzone.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    fileInput.click();
  }
});

Related patterns

• https://uxpatterns.dev/patterns/forms/text-field

---

For full implementation detail, examples, and testing notes, see references/pattern.md.

Pattern page: https://uxpatterns.dev/patterns/forms/file-input