A hook for uploading files using multipart form data with React Native. Provides a simple way to track upload progress, abort an upload, and handle timeouts. Written in TypeScript and no dependencies required.

npm version

example app


yarn add react-native-use-file-upload

Example App

There is an example app in this repo as shown in the above gif. It is located within example and there is a small node server script within example/server here. You can start the node server within example using yarn server. The upload route in the node server intentionally throttles the upload requests. You can read more about this in the FAQs below.


import useFileUpload, { UploadItem } from 'react-native-use-file-upload';

// Used in optional type parameter for useFileUpload
interface Item extends UploadItem {
  progress?: number;

// ...
const [data, setData] = useState<Item[]>([]);
// The generic type param below for useFileUpload is optional
// and defaults to UploadItem. It should inherit UploadItem.
const { startUpload, abortUpload } = useFileUpload<Item>({
  url: '',
  field: 'file',
  // Below options are optional
  method: 'POST',
  timeout: 60000,

const onPressUpload = async () => {
  const promises = => startUpload(item));
  // Use Promise.all instead if you want to throw an error from a timeout or error.
  // As of October 2022 you have to polyfill allSettled in React Native.
  const result = await Promise.allSettled(promises);



Start a file upload for a given file. Returns a promise that resolves with OnDoneData or rejects with OnErrorData.

// Objects passed to startUpload should have the below shape at least (UploadItem type)
  name: 'file.jpg',
  type: 'image/jpg',
  uri: 'file://some-local-file.jpg',


Abort a file upload for a given file. The promise from startUpload gets rejected and onError runs if present.

// Pass the uri of a file that started uploading


Name Type Required Description
url string Required The URL to send the request to.
field string Required The field name that will be used for the file in FormData.
method string Optional The HTTP method for the request. Defaults to “POST”.
headers Headers Optional Option for passsing in requst headers.

const headers = new Headers();
headers.append('Authorization', 'foo');
useFileUpload({ headers });
timeout number Optional The timeout value for the request in milliseconds.
onProgress function Optional Callback when a request times out for a given file. It receives 1 argument of this shape –

// OnProgressData type
  item: UploadItem; // or a type that inherits UploadItem
  event: ProgressEvent<EventTarget>;
// event is the XMLHttpRequest progress event object and it's shape is -
  loaded: number,
  total: number
onDone function Optional Callback on request completion for a given file. It receives 1 argument of this shape –

// OnDoneData type
  item: UploadItem; // or a type that inherits UploadItem
  responseBody: string; // eg "{\"foo\":\"baz\"}" (JSON) or "foo"
  responseHeaders: string;
onError function Optional Callback when a request error happens for a given file. It receives 1 argument of this shape –

// onErrorData type
  item: UploadItem; // or a type that inherits UploadItem
  error: string;
onTimeout function Optional Callback when a request error happens for a given file. It receives 1 argument of this shape –

// OnErrorData type
  item: UploadItem; // or a type that inherits UploadItem
  error: string;
  timeout: boolean; // true here


Do requests continue when the app is backgrounded?

Requests will time out if you background the app. This can be addressed by using react-native-background-upload.

The React Native team did a a heavy lift to polyfill and bridge XMLHttpRequest to the native side for us. There is an open PR in React Native to allow network requests to run in the background for iOS. There are plans to have a similar PR for Android as well. react-native-background-upload is great but if backgrounding can be supported without any native dependencies it is a win for everyone.

Why send 1 file at a time instead of multiple in a single request?

It is possible to to send multiple files in 1 request. There are downsides to this approach though and the main one is that it is slower. A client has the ability to handle multiple server connections simultaneously, allowing the files to stream in parallel. This folds the upload time over on itself.

Another downside is fault tolerance. By splitting the files into separate requests, this strategy allows for a file upload to fail in isolation. If the connection fails for the request, or the file is invalidated by the server, or any other reason, that file upload will fail by itself and won’t affect any of the other uploads.

How does the local node server throttle the upload requests?

The local node server throttles the upload requests to simulate a real world scenario on a cellular connection or slower network. This helps test out the progress and timeout handling on the client. It does this by using the node-throttle library. See the /upload route in here for the details.

How do I bypass the throttling on the local node server?

Set the url in useFileUpload to http://localhost:8080/_upload.

The onDone and promise from startUpload take awhile to resolve in the example app.

This is because of the throttling and can be bypassed.

Why is type and name required in the UploadItem type?

This is because of how React Native abstracts away setting the content-disposition request header for us in their polyfill for FormData. You can see here how that is being done in the getParts function.




View Github