Notoriously Psychedelic Modules


    1.3.0 • Public • Published

    react-native-background-upload npm version

    The only React Native http post file uploader with android and iOS background support. If you are uploading large files like videos, use this so your users can background your app during a long upload.


    npm install react-native-background-upload

    Automatic Native Library Linking

    react-native link react-native-background-upload

    Manual Native Library Linking


    1. In the XCode's "Project navigator", right click on your project's Libraries folder ➜ Add Files to <...>
    2. Go to node_modulesreact-native-background-uploadios ➜ select VydiaRNFileUploader.xcodeproj
    3. Add VydiaRNFileUploader.a to Build Phases -> Link Binary With Libraries


    1. Add the following lines to android/settings.gradle:

      include ':react-native-background-upload'
      project(':react-native-background-upload').projectDir = new File(rootProject.projectDir, '../node_modules/@jeremistadler/react-native-background-upload/android')
    2. Add the compile line to the dependencies in android/app/build.gradle:

      dependencies {
          compile project(':react-native-background-upload')
    3. Add the import and link the package in

      import com.vydia.RNUploader.UploaderReactPackage;  <-- add this import
      public class MainApplication extends Application implements ReactApplication {
          protected List<ReactPackage> getPackages() {
              return Arrays.<ReactPackage>asList(
                  new MainReactPackage(),
                  new UploaderReactPackage() // <-- add this line
    4. Ensure Android SDK versions. Open your app's android/app/build.gradle file. Ensure compileSdkVersion and targetSdkVersion are 25. Otherwise you'll get compilation errors.


    import Upload from 'react-native-background-upload'
    const options {
      url: '',
      path: 'file://path/to/file/on/device',
      method: 'POST',
      headers: {
        'my-custom-header': 's3headervalueorwhateveryouneed'
      // Below are options only supported on Android
      notification: {
        enabled: true
    Upload.startUpload(options).then((uploadId) => {
      console.log('Upload started')
      Upload.addListener('progress',uploadId, (data) => {
        console.log(`Progress: ${data.progress}%`)
      Upload.addListener('error',uploadId, (data) => {
        console.log(`Error: ${data.error}%`)
      Upload.addListener('completed',uploadId, (data) => {
    }).catch(function(err) {
      console.log('Upload error!',err)


    Does it support iOS camera roll assets?

    No, they must be converted to a file asset. The easist way to tell is that the url should always start with 'file://'. If not, it won't work. Things like react-native-image-picker provide you with both. PRs are welcome for this.

    Does it support multiple file uploads?

    Yes and No. It supports multiple concurrent uploads, but only a single upload per request. That should be fine for 90%+ of cases.

    Why should I use this file uploader instead of others that I've Googled like react-native-uploader?

    This package has two killer features not found anywhere else (as of 12/16/2016). First, it works on both iOS and Android. Others are iOS only. Second, it supports background uploading. This means that users can background your app and the upload will continue. This does not happen with other uploaders.


    Thanks to:


    npm i @jeremistadler/react-native-background-upload

    DownloadsWeekly Downloads






    Last publish


    • jeremistadler