elements
Manual UI Templates FileUpload

FileUpload

elements man ui/templates/file-upload

Drop, paste or browse for files; see them listed with previews, sizes, errors and progress.

Example
import { FileUpload } from "@elements/ui/file-upload";

<FileUpload files={form.photos} accept="image/*" maxFiles={5} maxFileSize={5_000_000} />
<FileUpload files={form.resume} accept={[".pdf", ".docx"]} name="resume" required />

Parts

Part What it is
.file-upload The root.
.file-upload-dropzone The drop target.
.file-upload-trigger The Browse button.
.file-upload-input The real file input, visually hidden.
.file-upload-list Accepted or rejected rows.
.file-upload-item A file row.
.file-upload-item-preview Thumbnail or kind icon.
.file-upload-item-delete Removes the row.
.file-upload-item-progress The upload bar.
.file-upload-clear Removes every file.

Attributes

Attribute Type Default Description
files File[] (two-way) [] Accepted files, as Elements Files with their bytes: pass them to an @rpc (opens in a new tab). Files already in the array on load are listed and in the input.
rejected FileRejection[] (two-way) [] Files the last pick refused, with error codes.
accept string | string[] | Record<string, string[]> "" Allowed types: MIME, type/*, or extensions.
maxFiles number 1 Most files. 1 replaces the file on each pick.
maxFileSize number Infinity Largest file in bytes.
minFileSize number 0 Smallest file in bytes.
directory boolean false Pick a whole folder.
capture "" | "user" | "environment" "" On phones, open the front or back camera.
allowDrop boolean true Files can be dropped on the dropzone.
allowPaste boolean true Files pasted while focus is inside are added.
preventDocumentDrop boolean true A drop that misses the dropzone does not open the file in the tab.
disableClick boolean false Clicking the dropzone does not open the picker.
trigger boolean true Shows the Browse button; without it the dropzone is the button.
preview boolean true Shows image thumbnails.
hint string "" A line under the title: allowed types and sizes.
progress Record<string, number> {} Upload percent by file name; draws a bar and announces when done.
locale string "" Locale for file sizes.
name string "" The input's name; FormData carries the files.
form string "" The id of the form the files belong to.
disabled boolean false Not interactive.
readonly boolean false Shows files; nothing adds or removes them.
required boolean false The form will not submit without a file.
invalid boolean false Marks the field invalid.
validate (file, details) => FileError[] | null null Return error codes to refuse a file.
transformFiles (files) => Promise<File[]> null Change files before they are read: resize, rename, convert.
translations Partial<FileUploadTranslations> {} Text, labels and error messages.
class string "" Extra classes on the root.
attrs Record<string, string | number | boolean | undefined> {} Attributes for the file input: id, aria-label, data-*.
onFileAccept (details: { files: File[] }) => void () => {} Files accepted by a pick, drop or paste.
onFileReject (details: { files: FileRejection[] }) => void () => {} Files refused, with codes.
onFileChange (details: { acceptedFiles, rejectedFiles }) => void () => {} After any change.

Slots

Slot Content
dropzone The dropzone's content. Default: an upload icon and a title.
trigger The Browse button's label.

Keyboard

Keys Action
Tab Moves to the Browse button, each delete button and clear.
Enter / Space On Browse (or the dropzone without one): opens the file picker.
Ctrl/Cmd + V Pastes files while focus is inside.

Data attributes

Attribute Values On
data-dragging present while files are dragged over root, dropzone
data-reading present while files are read root
data-invalid present when invalid or a file was refused root, dropzone, trigger
data-max-reached present at maxFiles root
data-disabled present when disabled root, dropzone, trigger, list, item, item name, size and preview
data-readonly present when read-only root, dropzone, trigger
data-type "accepted" | "rejected" list, item, item name, size, preview, delete
data-kind "image" | "video" | "pdf" | "file" item
data-errors the error codes rejected item

Accessibility

  • A real file input holds the files, so a Field label, required and form submission work natively; Browse points at it.
  • Without a Browse button the dropzone itself is a button that opens the picker with Enter or Space.
  • Added, refused and removed files and finished uploads are announced; progress bars are progressbars with a value.
  • After a delete, focus moves to the next delete button so it is never lost.

See also