UploadCard
UploadCard collects files by drag-and-drop or a file dialog, filters them by type and size, and lists them. It can
also upload them through its ref, with per-file progress. onChange reports every list change with the action type.When to use
- A form collects one or more files (images, PDFs, spreadsheets).
- Users should see each file, remove it, or watch its upload progress.
- Files are large and need chunked or resumable upload;
submit()sends each file in one XHR request. - A trigger button alone is enough — use the
useFileDialoghook.
Usage
PNG, JPEG, PDF
Arraste e solte aqui
ou
<UploadCard
accept={['image/*', 'application/pdf']}
acceptLabel="PNG, JPEG, PDF"
maxSize={10 * 1024 * 1024}
onChange={({ files, type }) => setFiles(files)}
onUnsupportedFile={(file) => notify(`${file.name} is not supported`)}
/>accept takes MIME types or extensions. A dialog selection with an unsupported type calls onUnsupportedFile and adds
nothing; dropped files of other types are skipped. Files over maxSize (default 15 MB) are skipped without a callback.
singleFile keeps one file. Set buttonText and removeFileLabel: their defaults are Portuguese.
Compact
compact renders a single row for dense forms. Both variants respond to their own width, not the viewport.
Uploading
The ref exposes submit(config), addFiles, removeFile, removeAll and files. Pass the request config to
submit; it merges over uploadConfig and resolves with the responses.
const uploadRef = useRef<UploadCardRef>(null);
const send = async () => {
const responses = await uploadRef.current?.submit({ endpoint: '/api/files' });
console.log(responses);
};
<UploadCard ref={uploadRef} accept={['application/pdf']} acceptLabel="PDF" />;Inside a Form, the ref is not reachable, so upload progress is unavailable; collect files there and upload
elsewhere. useFileControl() tracks addedFiles and removedFiles from onChange for edit flows.
Accessibility
- The file dialog button is the keyboard path; the drop area is pointer-only.
- Each remove button is icon-only and named
removeFileLabelplus the file name. acceptis a client-side filter, not a security check: validate files on the server.
Properties
accept *string[]noneacceptLabelstringnonebuttonTextstring'Enviar arquivos'classNamestringnonecompactbooleanfalsecustomButton((p: CustomButtonProps) => ReactNode)nonedisabledbooleannoneinitialFilesFileFile[]nonemaxSizenumber15728640 // 15 MBnamestringnoneonChange((value: UploadCardOnChangeValue) => void)noneonUnsupportedFile((f: File) => void)nonereadOnlybooleannoneremoveFileLabelstring'Remover arquivo'singleFilebooleanfalsestyleCSSPropertiesnoneuploadConfigUploadFileRequestConfignone