Upload
File upload control styled on top of a native <input type="file">. The input is focusable, keyboard-operable, and works with no JavaScript. Use accept to restrict file types and multiple to allow more than one file per submission. Drag-and-drop, per-file previews, progress bars, and client-side validation are deferred to a consumer-chosen third-party library initialized against the .upload element.
Usage
When to use
- A form needs the user to attach one or more files
- A drag-and-drop target is required for image or document upload
- File previews, progress, and per-item removal are needed
When not to use
- For a single avatar change - consider a simpler inline edit pattern
- For pasting rich content - use a content-editable region instead
Do
- Restrict
acceptto the file types the server can handle - Provide clear instructions about file size and format limits
- Announce file list changes to assistive tech
Don't
- Don't hide the native input so completely that it becomes unfocusable
- Don't rely solely on drag-and-drop - always provide a clickable label fallback
API
Slots
| Slot | Required | Description |
|---|---|---|
label | Yes | Visible label text for the file input. |
helper | - | Helper text rendered below the input. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | - | Name attribute for form submission. |
id | string | - | Associates the control with its label. Auto-generated when omitted. |
accept | string | - | Comma-separated list of allowed MIME types or file extensions. |
is_multiple | boolean | - | Allows selection of more than one file. |
is_disabled | boolean | - | Disables the control. |
is_required | boolean | - | Marks the control as required. |
is_invalid | boolean | - | Marks the control as invalid. Renders aria-invalid="true" when set. |
helper_id | string | - | ID of the helper element; the control gets aria-describedby pointing to it. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.required | Annotation | - | Marks the field as mandatory. |
Examples
Sizes
Sm, default, and lg variants stacked vertically. Padding, font size, and the file-selector button scale together.
Required
A required field, where the preceding label picks up its asterisk from the control rather than from any markup of its own.
Accessibility
- WCAG 2.2 AA
- The native
<input type="file">remains focusable and operable via the keyboard - The visible label is linked to the input via
for/id - File list changes are announced via
aria-live="polite" - Remove buttons have descriptive labels that include the file name
acceptandmultipledefine native input behavior; file size/count limits are enforced via JavaScript plus server-side validation (for exampledata-max-size/data-max-files) and surfaced viaaria-invalid
Dependencies
- close - per-file remove button uses the close component
- Optional: Dropzone, FilePond, or Uppy for progressive enhancement
Progressive enhancement
- No JS: native file input with a styled label; multiple file selection via
multiple; type filtering viaaccept; file size/count limits enforced via JS plus server-side validation (for exampledata-max-size/data-max-files) - With JS: drag-and-drop drop zone, file list with previews, per-file progress, client-side type/size validation, per-item remove action
- How to enable: include a third-party library (see Dependencies) and initialize it against the
.uploadelement
The base component works without JS. Advanced features can be added via well-maintained third-party libraries:
- Dropzone fork (NicolasCARPi) - actively maintained fork of the original Dropzone, no dependencies, drag-and-drop, progress, file validation
- FilePond - vanilla JS, CDN-ready, drag-and-drop, preview, reordering, file-type validation
- Uppy - modular, resumable uploads, large files
Related
- close - remove button used per file