FileUpload
Select and validate local files through a drop area or compact button.
Anatomy#
Usage#
Use FileUpload to collect local files before the application sends them. Selection and validation happen in the component; upload transport belongs to the caller.
Selecting files#
variant sets the appearance: area (the default) shows a large dashed drop area, and button
shows a compact picker button. Clicking anywhere in the visible control, including its padding, icon,
and text, opens the file picker. dropzone (default true) only controls whether files can be
dropped onto the control; it does not change how the control looks. File previews and removal
actions are outside the picker hit area.
Use multiple when the value can hold more than one File. New files are appended to the
selection, and value and onValueChange use a File[]. Without multiple, a new file replaces
the current one, and the value is File | null.
Selected file list#
The selected files appear in a list below the control, with an image thumbnail for image files and
fileIcon for other types. Set fileList={false} to omit the list and render the selection
yourself from onValueChange. Use itemRender to replace each entry. It receives file, index,
previewUrl, remove, and disabled, and must return an <li>.
Rejections and form behavior#
accept, minSize, maxSize, and maxFiles validate each picked or dropped file before it is
added. maxFiles counts files already selected and applies only with multiple. Rejected files are
reported to onValueInvalid as rejections with reason codes (FILE_INVALID_TYPE, FILE_TOO_SMALL, FILE_TOO_LARGE,
FILE_DUPLICATE, TOO_MANY_FILES); accepted files from the same batch are still added.
readOnly keeps the selected list visible but blocks adding and removing files. disabled removes
all interaction. Both inherit the enclosing Field’s state when omitted, and an explicit false
overrides it.
Keyboard interaction#
| Key | Description |
|---|---|
| ↵ / Space | Opens the native operating system file picker dialog when the upload control is focused. |
| ⇥ | Navigates between the upload control and individual file removal buttons. |
Examples#
Attach expense receipts#
Set multiple and maxFiles when the field holds a short list. Handle onValueInvalid when a fourth
file or a disallowed type is dropped.
Show rejected images#
Map onValueInvalid reason codes to messages. Validation runs before the file is added to the
value.
Attach from a compact button#
Set variant="button" for a compact picker button instead of the drop area. The selected file still
comes from onValueChange.
Bind attachments to a form#
Place FileUpload in form.Field so the schema owns required files and submit output.
Freeze uploads during maintenance#
disabled blocks new files. readOnly keeps the current list visible without allowing add or
remove.
API Reference#
Attributes#
data-disableddata-invaliddata-readonlydata-requireddata-draggingProps#
Props for the FileUpload component. Renders a <div> element by default.