Uploady

Package

@rpldy/uploady

Installation

npm

npm install @rpldy/uploady

Yarn

yarn add @rpldy/uploady

pnpm

pnpm add @rpldy/uploady

Props

Name (* = mandatory)	Type	Default	Description
Uploader Options
autoUpload	boolean	true	automatically upload files when they are added
destination	Destination	undefined	configure the end-point to upload to
grouped	boolean	false	group multiple files in a single request
maxGroupSize	number	5	maximum of files to group together in a single request
formatGroupParamName	(number, string) => string	undefined	determine the upload request field name when more than file is grouped in a single upload
fileFilter	FileFilter	undefined	return false to exclude from batch
method	string	"POST"	HTTP method in upload request
params	Object	undefined	collection of params to pass along with the upload (requires sendWithFormData = true)
forceJsonResponse	boolean	false	parse server response as JSON even if no JSON content-type header received
withCredentials	boolean	false	set XHR withCredentials to true
enhancer	UploaderEnhancer	undefined	uploader enhancer function
concurrent	boolean	false	issue multiple upload requests simultaneously
maxConcurrent	number	2	maximum allowed simultaneous requests
send	SendMethod	@rpldy/sender	how to send files to the server
sendWithFormData	boolean	true	upload is sent as part of formdata - when true, additional params can be sent along with uploaded data
formatServerResponse	FormatServerResponseMethod	undefined	function to create the batch item's uploadResponse from the raw xhr response
clearPendingOnAdd	boolean	false	whether to clear pending batch(es) when a new one is added
isSuccessfulCall	IsSuccessfulCall	undefined	callback to use to decide whether upload response is succssful or not
fastAbortThreshold	number	100	the pending/active item count threshold from which to start using the performant abort mechanism
userData	any	undefined	metadata 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
debug	boolean	false	enable console logs from uploady packages
listeners	Object	undefined	map of uploader events name and event handler
customInput	boolean	false	whether to use a custom file input (see: useFileInput
inputFieldName	string	"file"	name (attribute) of the file input field (requires sendWithFormData = true)
inputFieldContainer	HTMLElement	document.body	html element to place the file input element inside
children	React.Node	undefined	any part of your React app that will require access to the upload flow (components, hooks, etc.)
capture	string	null	input/file#capture - affects file input only. for example, drag&drop or programmatic uploads will not be affected by this setting
multiple	boolean	true	input/file#multiple - affects file input only. for example, drag&drop or programmatic uploads will not be affected by this setting
accept	string	null	input/file#accept - affects file input only. for example, drag&drop or programmatic uploads will not be affected by this setting
webkitdirectory	boolean	false	webkitdirectory - affects file input only. for example, drag&drop or programmatic uploads will not be affected by this setting
fileInputId	string	undefined	the value to use for the internal file input element
noPortal	boolean	false	Dont render Uploady's file input in a portal. (default: false) For SSR, noPortal = false causes a React warning in DEV.

Destination

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.

URL

The endpoint to make the request to

filesParamName

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

See inputFieldName

params

collection of params to pass along with the upload

headers

collection of headers to add to the request

method

Default: POST

The HTTP verb to use for the request

inputFieldName

Default: file

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

enhancer

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.

Extensions

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

fileFilter

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

listeners

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.

• See Uploader Events

• See Passing listeners using props

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.

formatServerResponseMethod

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

• See FormatServerResponseMethod

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

customInput

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.

clearPendingOnAdd

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.

isSuccessfulCall

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.

info

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}>
		...
		</Uploady>
	);
};

debug

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.

fastAbortThreshold

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.

userData

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) => {
    console.log(
      `BATCH ${batch.id} started uploading. found userData = ${options.userData}`,
    );
  });

No DOM Uploady

Missing Content