File upload
Accessible native file selection with optional drag-and-drop presentation.
When to use
Use a file upload field when users need to attach local files. Keep the native file picker as the primary path; offer drag and drop only as an additional input method.
Single file
Keep a visible label and the native file input. The browser-provided browse button remains keyboard accessible and continues to expose the selected filename without custom scripting.
Keep the input inside .file-upload to supply its design tokens. The .file-upload-dropzone wrapper is optional: without it, the input shows its own keyboard-focus ring; with it, the ring appears around the dropzone.
PNG or JPEG, up to 2 MB.
Choose a file or drop it here
No files selected.
<div class="file-upload">
<label class="form-label" for="avatar-file">Profile image</label>
<p class="file-upload-hint" id="avatar-file-hint">PNG or JPEG, up to 2 MB.</p>
<div class="file-upload-dropzone">
<p class="file-upload-prompt">Choose a file or drop it here</p>
<input
class="file-upload-input"
id="avatar-file"
name="avatar"
type="file"
accept="image/png,image/jpeg"
aria-describedby="avatar-file-hint avatar-file-summary" />
</div>
<div class="file-upload-summary" id="avatar-file-summary" aria-live="polite">
No files selected.
</div>
</div>accept is a picker hint, not validation. Validate the actual file type and size in the application and again on the server. Never trust a filename, extension or client-provided MIME type by itself.
Multiple files and selected-file summary
Add the native multiple attribute. This Showcase example updates the summary after selection; applications can use the same live region while keeping the input itself visible.
Select one or more PDF documents, up to 10 MB each.
Choose files or drop them here
No files selected.
The optional summary uses a semantic list and .file-upload-file-name to wrap long, unbroken names. Announce one concise summary per change; do not announce drag pointer movement.
Validation
Set aria-invalid="true" only after validation fails and include the visible error in aria-describedby. The error is not inferred from accept: application code owns file type, size, count and upload-result validation.
PDF, up to 10 MB.
Choose a PDF smaller than 10 MB.
<div class="file-upload">
<label class="form-label" for="invalid-file">Signed agreement</label>
<p class="file-upload-hint" id="invalid-file-hint">PDF, up to 10 MB.</p>
<input
class="file-upload-input is-invalid"
id="invalid-file"
name="agreement"
type="file"
accept="application/pdf"
aria-invalid="true"
aria-describedby="invalid-file-hint invalid-file-error" />
<p class="file-upload-feedback file-upload-feedback-error" id="invalid-file-error">
Choose a PDF smaller than 10 MB.
</p>
</div>Disabled
Use the native disabled attribute. Do not rely on subdued styling alone.
Drag and drop
Drag and drop is progressive enhancement. Keep the native browse control as the equivalent path, toggle .is-dragover only while accepted file items are over the target, and remove it on drop, drag leave and cancellation.
Visual preview of the active drop target.
Drop files to add them
Only accept DataTransferItem entries whose kind is file, ignore directory traversal APIs unless the product explicitly supports and audits them, and pass dropped files through the same count, type and size validation as files chosen through the picker. Do not remove the input, set it to display: none, or replace it with a pointer-only drop target.
Accessibility and behavior
- Keep a visible label connected to the native file input. Connect file restrictions, selected-file summaries and errors with
aria-describedby. - Preserve keyboard access to the browse control. A drop target needs the same validation and result handling as the native picker.
- The Showcase demonstrates selection summaries and drop handling. The package supplies styles; applications own file validation, transfer, cancellation and upload-result announcements.
CSS variables
Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--file-upload-gap | var(--spacer-2) | Space between child elements. | .file-upload |
--file-upload-dropzone-gap | var(--spacer-3) | Space between dropzone content. | .file-upload |
--file-upload-dropzone-padding | var(--spacer-4) | Dropzone inner spacing. | .file-upload |
--file-upload-dropzone-bg-color | var(--bg-surface) | Dropzone background. | .file-upload |
--file-upload-dropzone-border-width | var(--border-width) | Dropzone and native input border thickness. | .file-upload |
--file-upload-dropzone-border-color | var(--control-border-color) | Dropzone dashed border color. | .file-upload |
--file-upload-dropzone-border-radius | var(--border-radius-lg) | Dropzone corner radius. | .file-upload |
--file-upload-dropzone-hover-border-color | var(--primary-hover) | Dropzone border on hover. | .file-upload |
--file-upload-dropzone-active-bg-color | var(--bg-highlight) | Dropzone background while dragging a file over it. | .file-upload |
--file-upload-dropzone-active-border-color | var(--primary) | Dropzone border while dragging a file over it. | .file-upload |
--file-upload-input-bg-color | var(--bg-body) | Native file input background. | .file-upload |
--file-upload-input-border-color | var(--control-border-color) | Native file input border. | .file-upload |
--file-upload-input-border-radius | var(--border-radius) | Native file input corner radius. | .file-upload |
--file-upload-input-padding | var(--spacer-2) | Native file input inner spacing. | .file-upload |
--file-upload-button-bg-color | var(--bg-highlight) | Native file picker button background. | .file-upload |
--file-upload-button-hover-bg-color | var(--bg-active) | Native file picker button background on hover. | .file-upload |
--file-upload-button-color | var(--text-color) | Native file picker button text color. | .file-upload |
--file-upload-button-padding-y | var(--file-upload-input-padding) | Native file picker button top and bottom padding. | .file-upload |
--file-upload-button-padding-x | var(--spacer-3) | Native file picker button left and right padding. | .file-upload |
--file-upload-summary-color | var(--text-muted) | Selected-file summary text color. | .file-upload |
--file-upload-invalid-color | var(--error) | Accent color for invalid controls and feedback. | .file-upload (invalid) |
--file-upload-disabled-text-color | var(--disabled-text-color) | Text color while disabled. | .file-upload (disabled) |
--file-upload-disabled-bg-color | var(--disabled-bg-color) | Background color while disabled. | .file-upload (disabled) |
--file-upload-disabled-border-color | var(--disabled-border-color) | Border color while disabled. | .file-upload (disabled) |
--file-upload-focus-border-color | var(--primary-hover) | Border color while focused. | .file-upload (focus) |
--file-upload-focus-outline-width | var(--focus-outline-width) | Focus ring thickness. | .file-upload (focus) |
--file-upload-focus-outline-style | var(--focus-outline-style) | Focus ring line style. | .file-upload (focus) |
--file-upload-focus-outline-color | var(--focus-outline-color) | Focus ring color. | .file-upload (focus) |
--file-upload-focus-outline-offset | var(--focus-offset) | Distance between the focus ring and control. | .file-upload (focus) |
--file-upload-transition-duration | var(--transition-duration) | Duration of visual state transitions. | .file-upload |
--file-upload-transition-easing | var(--transition-easing) | Timing curve for visual state transitions. | .file-upload |