Skip to main content





npm install @rpldy/uploady


Name (* = mandatory)TypeDefaultDescription
Uploader Options
autoUploadbooleantrueautomatically upload files when they are added
destinationDestinationundefinedconfigure the end-point to upload to
groupedbooleanfalsegroup multiple files in a single request
maxGroupSizenumber5maximum of files to group together in a single request
formatGroupParamName(number, string) => stringundefineddetermine the upload request field name when more than file is grouped in a single upload
fileFilterFileFilterundefinedreturn false to exclude from batch
methodstring"POST"HTTP method in upload request
paramsObjectundefinedcollection of params to pass along with the upload (requires sendWithFormData = true)
forceJsonResponsebooleanfalseparse server response as JSON even if no JSON content-type header received
withCredentialsbooleanfalseset XHR withCredentials to true
enhancerUploaderEnhancerundefineduploader enhancer function
concurrentbooleanfalseissue multiple upload requests simultaneously
maxConcurrentnumber2maximum allowed simultaneous requests
sendSendMethod@rpldy/senderhow to send files to the server
sendWithFormDatabooleantrueupload is sent as part of formdata - when true, additional params can be sent along with uploaded data
formatServerResponseFormatServerResponseMethodundefinedfunction to create the batch item's uploadResponse from the raw xhr response
clearPendingOnAddbooleanfalsewhether to clear pending batch(es) when a new one is added
isSuccessfulCallIsSuccessfulCallundefinedcallback to use to decide whether upload response is succssful or not
fastAbortThresholdnumber100the pending/active item count threshold from which to start using the performant abort mechanism
userDataanyundefinedmetadata set by the user and isn't used by the upload process in any way, provided as a convenience to pass data around
Uploady Options
debugbooleanfalseenable console logs from uploady packages
listenersObjectundefinedmap of uploader events name and event handler
customInputbooleanfalsewhether to use a custom file input (see: useFileInput
inputFieldNamestring"file"name (attribute) of the file input field (requires sendWithFormData = true)
inputFieldContainerHTMLElementdocument.bodyhtml element to place the file input element inside
childrenReact.Nodeundefinedany part of your React app that will require access to the upload flow (components, hooks, etc.)
capturestringnullinput/file#capture - affects file input only. for example, drag&drop or programmatic uploads will not be affected by this setting
multiplebooleantrueinput/file#multiple - affects file input only. for example, drag&drop or programmatic uploads will not be affected by this setting
acceptstringnullinput/file#accept - affects file input only. for example, drag&drop or programmatic uploads will not be affected by this setting
webkitdirectorybooleanfalsewebkitdirectory - affects file input only. for example, drag&drop or programmatic uploads will not be affected by this setting
fileInputIdstringundefinedthe value to use for the internal file input element
noPortalbooleanfalseDont render Uploady's file input in a portal. (default: false) For SSR, noPortal = false causes a React warning in DEV.


type Destination = {
url?: string;
filesParamName?: string;
params?: Record<string, unknown>;
headers?: Record<string, unknown>;
method?: string;

The destination is how you tell Uploady (and the Uploader) where to upload to. In most cases, this means an HTTP endpoint.

There are a few Props such as: params and method that both Uploady accepts directly and can also be passed inside the Destination object. The destination has the higher priority and will override the ones configured outside.


The endpoint to make the request to


The name of the param in the upload request (default: input element's name)

See inputFieldName


collection of params to pass along with the upload


collection of headers to add to the request


Default: POST

The HTTP verb to use for the request


Default: file

This is the name that will be assigned to the file input element rendered by Uploady.


type UploaderEnhancer = (uploader: UploaderType, trigger: Trigger<any>) => UploaderType;

Registering an enhancer gives you access to the uploader instance and to the trigger method. This is a powerful way to customize the uploader or its options.

The trigger method can be used to trigger(fire) custom events that can be listened to using the listeners prop or the on and once context methods.


Enhancers are the only time when external code can register an extension. Extensions are objects that are added to an uploader instance under a specific name and can later be retrieved. This is mainly used internally by the other providers.

See Uploader Enhancers Guide for more details


type FileFilterMethod = (file: File | string, index: number, files: File[] | string[]) => boolean | Promise<boolean | undefined> | undefined;

the file filter method is called on each item being uploaded (typically: File) and should return false (or a falsy value) in case it shouldn't be added to the batch.

the filter method supports async (returning a promise) responses.

See File Filter Guide


Makes it possible to pass an object map of key being the event name (ex: "BATCH-START") and the value being a handler function. The event handlers passed using this object map will be registered using the Context's on method.

Send Method​

export type SenderProgressEvent = {
total: number;
loaded: number;

type OnProgress = (e: SenderProgressEvent, objs: Record<string, unknown>[]) => void;

type SendMethod = (item: BatchItem[], url: string | undefined, options: SendOptions, onProgress?: OnProgress) => SendResult;

This is the method that will be called by the uploader when its time to start making upload requests. The default send method comes from the XHR Sender.

It's possible to replace the default method with any other sender that provides the same signature the uploader expects.

Providers like Chunked-Uploady, use the ability to swap the send method in order to provide the one from their own sender. ie: Chunked-Sender.


A function to create the batch item's uploadResponse from the raw xhr response.

If not provided, JSON responses will be parsed using JSON.parse or be left as fis for anything else.


Uploady render's a (hidden) file input that is used to show the file selection prompt to the user in order to select local files to upload. In almost all cases that is the preferred way and therefore the default. In case you want to use your own file input, this can be achieved by setting the prop to true, and using the useFileInput hook to pass a ref to the custom element.


When uploader is set up with autoUpload = false, files added (batches) will not automatically upload and a call to upload is required. Setting this option to true will remove previously added batch(es) and leave only the new one to upload.


type IsSuccessfulCall = (xhr: XMLHttpRequest) => boolean;

Uploady's sender treats server responses as successful when they have one of these status codes: 200, 201, 202, 203, 204.

In case you have a server that returns a different code or you want to specify your own logic to determine the success of the call, isSuccessfulCall gives you the chance to do so, overriding the default behavior.


The callback can be asynchronous

//determine successful call using custom status codes
const customIsSuccess = (xhr) => [308, 418].includes(xhr.status);

const App = () => {
return (
<Uploady isSuccessfulCall={customIsSuccess}>


Default: false

Most of the time there is no need to use this flag. When setting to true it will make Uploady and other internal classes log debugging information to the console.


Default: 100

Added in 1.1.0

Controls the way abort of multiple items (all or batch) is handled by the Abort Enhancer. When the count of items to abort it equal or higher than the threshold, the fast abort mode is used. If not, or when the threshold is set to 0, the normal mode is used.


this can be anything you want to set. It is ignored by the Uploader and is provided as a convenience to pass information around. For example, from the code initiating the upload and event handler.

	//add userData for uploads started by this button:
return <UploadButton userData="test"/>

// somewhere else:
useBatchStartListener((batch, options) => {
`BATCH ${} started uploading. found userData = ${options.userData}`,

No DOM Uploady​

Missing Content