Uploader
Take files from people and show each upload's progress, with Cancel and Retry.
Use an uploader when people send files that take a while to upload. It has a drop zone with a browse button, and a row for each upload with its progress bar.
- quarterly-report.pdf42% ยท 2.4 MB
- team-offsite.jpg3.1 MB
- training-set.csvUpload failed
Installation
npx shadcn@latest add @kind-ui/uploaderUsage
Uploads
You upload the files and own items. onFiles gets the files someone chooses, drops or pastes; add an item for each, then update its progress (0 to 100) and status as it uploads: queued, uploading, done, error or cancelled. Each row's progress bar is named by the file, and the line under it shows what the upload is doing and the file's size. A failed row shows the item's error, or "Upload failed".
When an upload finishes or fails, screen readers hear "report.pdf uploaded" or "report.pdf failed", once.
A row added later fades in. When you take an item out of items, its row stays in place and fades out, hidden from assistive technology and out of reach, then the rows after it slide up into its place; if its button had focus, focus moves to the next row's button first. Under prefers-reduced-motion, or with motion="reduced", it fades over 120 ms and nothing slides, and with motion="none" it leaves at once.
Limits
Pass accept and maxSize to limit the files. The ones they rule out go to onReject instead of onFiles, each with its reasons.
Cancel and Retry
Pass onCancel to show Cancel on queued and uploading rows, and onRetry to show Retry on failed ones. Each gets the item's id. A row takes no second press until you change its status, so a double click can't retry and then cancel. When a cancelled row's button leaves, focus moves to the next row's button, or the one before at the end.
API Reference
Prop
Type
Agent
An agent connected with createAgent reads the uploader's items. It can run these actions while an item can take them:
Prop
Type
Neither action waits for a person to confirm, since a cancelled upload can be added again. To ask the person first, return their answer from your allow, which also answers every action that does need a person:
import { createAgent } from "@ui-sdk/react/agent";
const agent = createAgent({
allow: ({ component, action, confirm }) => {
if (confirm) return window.confirm(confirm);
if (component === "kind-uploader") return window.confirm(`Let the agent ${action} an upload?`);
return true;
},
});Runs in React and Web Components. On <kind-uploader>, items is a property and the other props are kebab-case attributes, so maxSize is max-size. Accepted files fire files, and turned-down ones uploadreject. Cancel and Retry need the can-cancel and can-retry attributes, and fire uploadcancel and uploadretry with the item's id.