Usage
Configure Drop Upload through props on the <DropUpload /> component. The
most commonly used settings are grouped here:
- File validation — restrict which files can be selected
- Customization — labels, colors, and behavior
- Language (i18n) — locales and string overrides
- Callbacks — hook into drop, change, and discard events
Size limits (minFileSize/maxFileSize), maxFiles, and allowedFormats
are all enforced client-side — but this happens in the browser, so it helps users
pick the right files rather than acting as a security boundary. Always
validate uploads again in your own backend.
Full props reference
| Prop | Type | Default | Description |
|---|---|---|---|
| borderSolid | boolean | false | Draws the drop area with a solid border instead of the default dotted one. Accent colors have their own props: dragBorderColor, spotlightColor and dropSmokeColor. |
| allowedFormats | string[] | [] | MIME types (or wildcards like "image/*") to accept. Rejected client-side. |
| allowedFormatsLabelMode | "auto" | "auto-extended" | "custom" | "off" | "auto" | Controls how allowed formats are described to the user. |
| allowedFormatsLabelCustomText | string | "" | Custom label text, used when labelMode is "custom". |
| maxFiles | number | 0 | Maximum number of files that can be attached. 0 means unlimited. Extra files are never attached and are reported through onFilesRejected. |
| maxFileSize | number | 0 | Maximum file size in KB. 0 means no limit. Rejected client-side. |
| minFileSize | number | 0 | Minimum file size in KB. 0 means no limit. Rejected client-side. |
| instructionLabel | string | locale's instruction copy | Main call-to-action text in the drop area. |
| locale | "en" | "es" | "en" | Language used for the component's built-in copy (instructions, retry, upload failed, etc.). |
| translations | Partial<DropUploadTranslations> | undefined | Override individual strings on top of the selected locale. |
| initialAttachedFileList | AttachedFile[] | [] | Pre-populate the attached file list. |
| variant | "default" | "avatar" | "default" | Shape of the drop area. "avatar" swaps the rectangle and the file list for a single circular well holding one image. Validation, uploads and callbacks are identical in both. |
| pasteToUpload | boolean | true | Attach files pasted from the clipboard (Ctrl/Cmd+V), with the same validation as a drop. Pastes over an input, textarea or contenteditable are left alone, and with several uploaders on the page only one takes it. |
| avatarCrop | boolean | true | Let the visitor pan and zoom the image inside the circle before upload, so the adapter receives the crop and not the original. Only applies to variant="avatar" and to image files. |
| avatarCropSize | number | 512 | Side in px of the square the cropper exports. |
| avatarSize | number | 160 | Diameter in px of the circle drawn by variant="avatar". |
| fileListMode | "list" | "stacked" | "list" | "stacked" shows only the most recent file and collapses the rest into a pile that expands on click. |
| autoHideDropArea | boolean | false | Hide the drop area once at least one file is attached. |
| discardFileAwaitTime | number | 700 | Long-press delay (ms) before a file can be discarded. 0 disables the long press. |
| debugMode | boolean | false | Shows the native file input and extra logging. Dev only. |
| spotlight | boolean | true | Toggles the hover spotlight effect in the drop area. |
| spotlightColor | string | "#60a5fa" | Color of the spotlight that follows the cursor while dragging files over the drop area. Any CSS color. |
| dragBorderColor | string | "#3b82f6" | Color of the inner border glow shown while dragging files over the drop area, and of the per-file progress bar. Any CSS color. |
| dropSmoke | boolean | true | Puff of smoke thrown at the point a file lands on the drop area. Skipped anyway when the visitor asked their OS to reduce motion. |
| dropSmokeColor | string | follows the theme | Color of that smoke. Any CSS color. Left alone, the cloud is grey on light and pale on dark. |
| onFilesDropped | (files: FileList) => void | — | Fires on drag-and-drop. |
| onFilesChanged | (files: FileList) => void | — | Fires on any file-input change (drop or click-to-browse). |
| onDiscardFile | (file: AttachedFile) => void | — | Fires when a file is removed. |
| onFilesRejected | (rejectedFiles: RejectedFile[]) => void | — | Fires when one or more files fail validation — size limits, disallowed type, spoofed content, too many files, or a dropped folder. |
| uploadAdapter | UploadAdapter | undefined | Drives the actual upload (see Uploading docs). Without it, files are only picked and previewed. |
| autoUpload | boolean | true | Start uploading automatically once a file passes validation. Set false and each file waits for its own upload button in the list, or for the ref's startUpload(). |
| onUploadComplete | (file: AttachedFile) => void | — | Fires when a file finishes uploading successfully. The file carries the url reported by the adapter. |
| onUploadError | (file: AttachedFile, error: unknown) => void | — | Fires when a file fails to upload. |
| onUploadCancel | (file: AttachedFile) => void | — | Fires when an upload in flight is aborted — the stop button, discarding the file, replacing the avatar's picture, or the cancelUpload() ref method. Not fired on unmount. |
| darkMode | "dark" | "light" | "system" | "light" | Color theme. "system" follows the visitor's OS preference (prefers-color-scheme) and updates live if it changes. |