V2 to V3 migration

react-native-document-picker's (RNDP) API has changed a fair bit between V2 and V3.

V2 Example

DocumentPicker.show({
  filetype: [DocumentPickerUtil.images()],
}, (error,res) => {
  console.log(
    res.uri,
    res.type, // mime type
    res.fileName,
    res.fileSize
  );
});

V3 Example

// Async/Await
try {
  const res = await DocumentPicker.pick({
    type: [DocumentPicker.types.images],
  });
  console.log(
     res.uri,
     res.type, // mime type
     res.name,
     res.size
  );
} catch ( err ) {
  if ( DocumentPicker.isCancel(err) ) {
    // User cancelled the picker, exit any dialogs or menus and move on
  } else {
    throw err;
  }
}

// Promises
DocumentPicker.pick({type: [DocumentPicker.types.images]})
  .then((res) => {
    console.log(
       res.uri,
       res.type, // mime type
       res.name,
       res.size
    );
  })
  .catch((err) => {
    if ( DocumentPicker.isCancel(err) ) {
      // User cancelled the picker, exit any dialogs or menus and move on
    } else {
      throw err;
    }
  });

Changes

Minimum Version

RNDP now requires at least version 0.33 of react-native.

Android namespace changed

The Android namespace and class have been changed.

In your MainApplication.java make the following replacements:

- import com.reactnativedocumentpicker.ReactNativeDocumentPicker;; // Import package
+ import io.github.elyx0.reactnativedocumentpicker.DocumentPickerPackage; // Import package

-             new ReactNativeDocumentPicker() // Add package
+             new DocumentPickerPackage() // Add package

Import

RNDP's two named DocumentPicker and DocumentPickerUtil exports have been replaced with a single default export of DocumentPicker.

Old:

import { DocumentPicker, DocumentPickerUtil } from 'react-native-document-picker';

New:

import DocumentPicker from 'react-native-document-picker';

An ES6 module export is now used so CommonJS code will need to require the default export.

var DocumentPicker = require('react-native-document-picker').default;

show -> pick and new pickMultiple

The show function has been replaced with a pick function. A new pickMultiple has been added that supports muliple document selection and returns an array of results.

The filetype option has been renamed to type and will now also accept a string for a single type and will default to allFiles if you omit it.

Android now accepts multiple MIME types. However Android Jellybean does not support this and will now fall back to */* when you provide more than 1 type instead of using only the first type in the list.

The depreciated document provider menu on iOS has been removed and now document providers are opened directly. Because of this the iPad specific top and left options have been dropped as they are no longer relevant.

Callbacks -> Promises

The pick (formerly show) function no longer takes a node style callback as its second argument. The pick function now returns a Promise that will be resolved with the result(s) or rejected with the error.

The error on rejection is now an actual Error object with a helpful error code instead of a string.

Cancellation

Previously RNDP handled cancellation inconsistently. On iOS when cancelled the callback would never be run. On Android the callback would be called with a "Bad result code: 0" string as the error argument.

RNDP will now reject the Promise with a cancellation error on both Android and iOS. You can check if an error is a cancellation error using DocumentPicker.isCancel(err).

Result

The result object(s) of a pick has changed:

• type is now available on iOS
• fileName is now name to reflect the fact that sometimes it may not be an actual filename
• fileSize is now size

In the past Android may have returned file:// or http(s):// uri values on pre-KitKat devices, due to use of the obsolete and improperly used PICK action. On Android the uri is now guaranteed to be a content:// URI that must be used with a ContentResolver.

DocumentPickerUtil / types

The DocumentPickerUtil export has been dropped, the type functions on it have been replaced with a types map on DocumentPicker.

V2	V3
DocumentPickerUtil.allFiles()	DocumentPicker.types.allFiles
DocumentPickerUtil.images()	DocumentPicker.types.images
DocumentPickerUtil.plainText()	DocumentPicker.types.plainText
DocumentPickerUtil.audio()	DocumentPicker.types.audio
DocumentPickerUtil.pdf()	DocumentPicker.types.pdf