Skip to the content

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.
Forms

When to use

Use when
  • A form collects one or more files (images, PDFs, spreadsheets).
  • Users should see each file, remove it, or watch its upload progress.
Avoid when
  • 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 useFileDialog hook.

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 removeFileLabel plus the file name.
  • accept is a client-side filter, not a security check: validate files on the server.

Properties

See also