Upload
v1.0.18Updated 19 Oct 2026Upload component with four visual variants (default panel / compact / avatar / gallery), drag-drop, per-file progress, pause / resume / retry, and DnD reorder.
Preview
Live · 13 stories▸Why this is recommendedformuploadfiledropzone+4
The default, out-of-the-box Upload.
- ✓Resumable multi-file uploads
- ✓Image gallery uploads
- ✓Document attachment pickers
- ✓A one-file picker whose parent does its own PUT and must let the user pick again after the server refuses the file
- Variants: default panel / compact / avatar / gallery
- Spreads the remaining props onto the root element of every variant (data-* hooks, id, style, aria-*), with the built-in data-slot="upload" / data-variant hooks winning over a caller that tries to overwrite them
- Drag-drop zone with hover affordance
- Per-file progress bar
- Pause / resume / retry per upload
- DnD reorder of accepted files
- Rejection feedback (size / type / count), dismissible so a refusal never stares back for ever
- Recovery after a failed attempt: onFiles may return false (or reject) to mark those files failed; a failed entry frees its maxFiles slot; `ref` exposes reset() / remove(id) / fail(ids) / clearRejections() / openPicker()
- replaceAtLimit — at the maxFiles limit a new pick replaces the oldest instead of being refused (default for maxFiles=1)
- i18n: labels prop overrides every built-in string (status pills, rejection reasons, dropzone prompt/helper, aria-labels); percentages and byte sizes format through LocaleProvider (prettyBytes accepts an optional FormatLocale)
- ✕Single trivial file input (use Input type="file")
- ✕File browser (use FileBrowser)
Install
Ask your agent, or call the MCP tool directly. The resolved bundle is written into your project.
Usage
Tick variants in the left menu — each adds a tab with that variant’s real story source, the same code the preview above renders.
Props
variantVisual layout
—onUploadUpload handler returning a progress observable
—onFilesThe accepted files, handed over once they pass validation. Return or resolve false — or throw/reject — to tell the component your own transfer failed: those entries flip to failed, the error shows on the row with its remove button, and they stop occupying a maxFiles slot so the next pick is accepted. MCP feedback fb_96fd8fb9.
—replaceAtLimitAt the maxFiles limit, let a new pick replace the oldest entries instead of being rejected. Defaults to true when maxFiles is 1 (a one-slot picker is a "choose a file" control); pass false for the strict refusal. MCP feedback fb_96fd8fb9.
—refImperative handle: reset() empties the queue and the rejection banner, remove(id) drops one entry, fail(ids?, error?) marks entries failed with your own message, clearRejections() clears the banner, openPicker() opens the file dialog. This is how a parent that runs its own upload recovers the control after a refusal. MCP feedback fb_96fd8fb9.
—acceptAllowed MIME types or extensions
—maxFilesMax total files
—maxSizeMax single-file size in bytes
—pausableAllow pause / resume per file
—reorderableAllow DnD reorder of files
—labelsOverride any built-in UI string — status pills, rejection reasons, dropzone prompt ({browse} token), action aria-labels (i18n). Merged over DEFAULT_UPLOAD_LABELS; {token} templates for parameterized strings. Percentages and byte sizes follow LocaleProvider.
—...propsEvery remaining standard div attribute is spread onto the root of whichever variant renders — data-* hooks, id, style, title, aria-describedby. The spread goes FIRST, so the built-in data-slot="upload" and data-variant hooks and the merged className can never be clobbered by a caller.
—