Upload Progress
Control progress reporting granularity for custom progress UIs.
The uploadProgressGranularity prop controls how often the upload state machine updates its progress value during an upload. Lower granularity = fewer state updates = fewer re-renders.
| Value | Behavior |
|---|---|
'coarse' (default) | Progress reported in ~10% increments |
'fine' | Every ~5% increment |
'all' | Every underlying XHR progress event — highest frequency, use for smooth animated bars |
Reading progress
UploadButton and UploadDropzone render their own progress bar automatically. If you want to render your own progress UI around an upload, use the useUploadKit hook — it exposes a reactive progress number (0–100) alongside status, error, and result.
import { useUploadKit } from '@uploadkitdev/react';
export default function CustomUploader() {
const { upload, progress, isUploading } = useUploadKit('imageUploader');
async function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
const file = e.target.files?.[0];
if (!file) return;
await upload(file, undefined, { progressGranularity: 'all' });
}
return (
<div>
<input type="file" accept="image/*" onChange={handleChange} />
{isUploading && (
<div style={{ width: '100%', background: '#eee', borderRadius: 4 }}>
<div
style={{
width: `${progress}%`,
height: 4,
background: '#6366f1',
borderRadius: 4,
transition: 'width 80ms linear',
}}
/>
<span>{progress}%</span>
</div>
)}
</div>
);
}Passing granularity to built-in components
UploadButton and UploadDropzone accept uploadProgressGranularity directly as a prop. The built-in progress bar uses the same value internally:
<UploadButton route="imageUploader" uploadProgressGranularity="all" />
<UploadDropzone route="documentUploader" uploadProgressGranularity="fine" />Use 'coarse' (the default) unless you are rendering a custom animated progress bar. Frequent state updates from 'all' can cause extra re-renders in your React tree.
Choosing the right value
'coarse'— default; suitable for showing a simple progress indicator with minimal overhead'fine'— good for progress bars that should feel responsive without maximum update frequency'all'— use only when you need a smooth, frame-rate animation tied directly to XHR events