🚧🚧 GH discussions available 🚧🚧
If you want to ask questions, we opened GH discussions for that purpose! 🤗 Issue tracker is now reserved for bugs and feature requests only and issues not following the issue template can be closed. Thank you!
A React Native wrapper for:
- Apple's
UIDocumentPickerViewController - Android's
Intent.ACTION_GET_CONTENT - Windows
Windows.Storage.Pickers
Requires RN >= 0.63, Android 5.0+ and iOS 11+
npm i --save react-native-document-picker
OR
yarn add react-native-document-pickerIf you are using RN >= 0.63, only run pod install from the ios directory. Then rebuild your project. Older RN versions are not supported.
DocumentPicker.pickMultiple(options) / DocumentPicker.pickSingle(options) / DocumentPicker.pick(options)
pick returns a Promise<Array<DocumentPickerResponse>> instead of Promise<DocumentPickerResponse>. If you were using pick, change those usages to pickSingle.
Use pickMultiple, pickSingle or pick to open a document picker for the user to select file(s). All methods return a Promise.
Open a system directory picker. Returns a promise that resolves to ({ uri: string }) of the directory selected by user.
pickis the most universal, you can useallowMultiSelectionparam to control whether or not user can select multiple files (falseby default). Returns aPromise<Array<DocumentPickerResponse>>
pickSingle and pickMultiple are "sugar functions" on top of pick, and they might be removed in a future release for increased API clarity.
pickSinglewill only allow a single selection and the Promise will resolve to that single result (same behavior aspickin v5)pickMultiplewill allow multiple selection and the Promise will resolve to an array of results.
All of the options are optional
Whether or not selecting multiple files is allowed. For pick, this is false by default. allowMultiSelection is false for pickSingle and true for pickMultiple and cannot be overridden for those calls.
The type or types of documents to allow selection of. May be an array of types as single type string.
- On Android these are MIME types such as
text/plainor partial MIME types such asimage/*. See common MIME types. - On iOS these must be Apple "Uniform Type Identifiers"
- If
typeis omitted it will be treated as*/*orpublic.item.
Defaults to import. If mode is set to import the document picker imports the file from outside to inside the sandbox, otherwise if mode is set to open the document picker opens the file right in place.
If specified, the picked file is copied to NSCachesDirectory / NSDocumentDirectory (iOS) or getCacheDir / getFilesDir (Android). The uri of the copy will be available in result's fileCopyUri. If copying the file fails (eg. due to lack of space), fileCopyUri will be the same as uri, and more details about the error will be available in copyError field in the result.
This should help if you need to work with the file(s) later on, because by default, the picked documents are temporary files. They remain available only until your application terminates. This may impact performance for large files, so keep this in mind if you expect users to pick particularly large files and your app does not need immediate read access.
Defaults to false. If readContent is set to true the content of the picked file/files will be read and supplied in the result object.
-
Be aware that this can introduce a huge performance hit in case of big files. (The files are read completely and into the memory and encoded to base64 afterwards to add them to the result object)
-
However reading the file directly from within the Thread which managed the picker can be necessary on Windows: Windows Apps can only read the Downloads folder and their own app folder by default and If a file is outside of these locations it cannot be acessed directly. However if the user picks the file through a file picker permissions to that file are granted implicitly.
In addition to the default locations, an app can access additional files and folders by declaring capabilities in the app manifest (see App capability declarations), or by calling a file picker to let the user pick files and folders for the app to access (see Open files and folders with a picker).https://docs.microsoft.com/en-us/windows/uwp/files/file-access-permissions
Unfortunately that permission is not granted to the whole app, but only the Thread which handled the filepicker. Therefore it can be useful to read the file directly.
-
You can use
react-native-fson Android and IOS to read the picked file.
The pick Promise resolves to an array of objects with the following keys.
The URI representing the document picked by the user. On iOS this will be a file:// URI for a temporary file in your app's container if mode is not specified or set at import otherwise it will be the original file:// URI. On Android this will be a content:// URI for a document provided by a DocumentProvider that must be accessed with a ContentResolver.
Same as uri, but has special meaning if copyTo option is specified.
The MIME type of the file. On Android some DocumentProviders may not provide MIME types for their documents. On iOS this MIME type is based on the best MIME type for the file extension according to Apple's internal "Uniform Type Identifiers" database.
The display name of the file. This is normally the filename of the file, but Android does not guarantee that this will be a filename from all DocumentProviders.
The file size of the document. On Android some DocumentProviders may not provide this information for a document.
The base64 encoded content of the picked file if the option readContent was set to true.
DocumentPicker.types.* provides a few common types for use as type values, these types will use the correct format for each platform (MIME types on Android, UTIs on iOS).
DocumentPicker.types.allFiles: All document types, on Android this is*/*, on iOS ispublic.itemDocumentPicker.types.images: All image typesDocumentPicker.types.plainText: Plain text filesDocumentPicker.types.audio: All audio typesDocumentPicker.types.pdf: PDF documentsDocumentPicker.types.zip: Zip filesDocumentPicker.types.csv: Csv filesDocumentPicker.types.doc: doc filesDocumentPicker.types.docx: docx filesDocumentPicker.types.ppt: ppt filesDocumentPicker.types.pptx: pptx filesDocumentPicker.types.xls: xls filesDocumentPicker.types.xlsx: xlsx files
If the user cancels the document picker without choosing a file (by pressing the system back button on Android or the Cancel button on iOS) the Promise will be rejected with a cancellation error. You can check for this error using DocumentPicker.isCancel(err) allowing you to ignore it and cleanup any parts of your interface that may not be needed anymore.
If mode is set to open iOS is giving you a secure access to a file located outside from your sandbox.
In that case Apple is asking you to release the access as soon as you finish using the resource.
import DocumentPicker from 'react-native-document-picker'
// Pick a single file
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
}
}
// Pick multiple files
try {
const results = await DocumentPicker.pickMultiple({
type: [DocumentPicker.types.images],
})
for (const res of results) {
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
}
}
Use blob support that is built-in into react natve - see comment.
Alternatively, use https://github.com/johanneslumpe/react-native-fs
I had to modify Uploader.m so it would use NSFileCoordinator with NSFileCoordinatorReadingForUploading option.
I added a check for file length that would be thrown into RNFS catch block.
if ([fileData length] == 0) {
NSError *errorUp = [NSError errorWithDomain:@"com.whatever.yourapp" code:77 userInfo:[NSDictionary dictionaryWithObject:@"empty" forKey:NSLocalizedDescriptionKey]];
_params.errorCallback(errorUp);
return;
}let url = 'file://whatever/com.bla.bla/file.ext' //The url you received from the DocumentPicker
// I STRONGLY RECOMMEND ADDING A SMALL SETTIMEOUT before uploading the url you just got.
const split = url.split('/')
const name = split.pop()
const inbox = split.pop()
const realPath = `${RNFS.TemporaryDirectoryPath}${inbox}/${name}`
const uploadBegin = (response) => {
const jobId = response.jobId
console.log('UPLOAD HAS BEGUN! JobId: ' + jobId)
}
const uploadProgress = (response) => {
const percentage = Math.floor((response.totalBytesSent / response.totalBytesExpectedToSend) * 100)
console.log('UPLOAD IS ' + percentage + '% DONE!')
}
RNFS.uploadFiles({
toUrl: uploadUrl,
files: [
{
name,
filename: name,
filepath: realPath,
},
],
method: 'POST',
headers: {
Accept: 'application/json',
},
begin: uploadBegin,
beginCallback: uploadBegin, // Don't ask me, only way I made it work as of 1.5.1
progressCallback: uploadProgress,
progress: uploadProgress,
})
.then((response) => {
console.log(response, '<<< Response')
if (response.statusCode == 200) {
//You might not be getting a statusCode at all. Check
console.log('FILES UPLOADED!')
} else {
console.log('SERVER ERROR')
}
})
.catch((err) => {
if (err.description) {
switch (err.description) {
case 'cancelled':
console.log('Upload cancelled')
break
case 'empty':
console.log('Empty file')
default:
//Unknown
}
} else {
//Weird
}
console.log(err)
})- Fix Xcode warning about constraints
- support options for the UIDocumentPickerViewController