@spicysparks/react-native-document-picker
v9.0.2
Published
A react native interface to access documents from dropbox, google drive, iCloud...
Downloads
17
Readme
react-native-document-picker
🚧🚧 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.69, Android 5.0+ and iOS 11+
Table of Contents
- react-native-document-picker
- Installation
- RN >= 0.69
- API
- pickSingle(options) / pick(options)
- pickDirectory()
- Options
- allowMultiSelection:boolean
- type:string|Array<string>
- [iOS and Android only] copyTo:"cachesDirectory" | "documentDirectory"
- [iOS only] presentationStyle:'fullScreen' | 'pageSheet' | 'formSheet' | 'overFullScreen'
- [iOS only] transitionStyle:'coverVertical' | 'flipHorizontal' | 'crossDissolve' | 'partialCurl'
- [iOS only] mode:"import" | "open"
- [Windows only] readContent:boolean
- Result
- types.*
- Example
- How to upload picked files?
- Help wanted: Improvements
Installation
React Native
npm i --save react-native-document-picker
OR
yarn add react-native-document-picker
import DocumentPicker from 'react-native-document-picker'
Expo
This package is supported in Expo managed workflow through the usage of custom development clients.
expo install react-native-document-picker
# Create a development build (provided you have expo-dev-client installed and set up)
eas build
# Or run it locally
expo prebuild
expo run:ios
expo run:android
RN >= 0.69
If you are using RN >= 0.69, only run pod install
from the ios directory. Then rebuild your project. Older RN versions are not supported.
New architecture is supported with RN >= 71.
API
pickSingle(options)
/ pick(options)
⚠️ Breaking in v6: pick
returns a Promise<Array<DocumentPickerResponse>>
instead of Promise<DocumentPickerResponse>
. If you were using pick
, change those usages to pickSingle
.
Use pickSingle
or pick
to open a document picker for the user to select file(s).
with
pick
, you can useallowMultiSelection
param to control whether user can select multiple files (false
by default). Returns aPromise<Array<DocumentPickerResponse>>
pickSingle
is "sugar function" on top ofpick
and only allows a single selection returnsPromise<DocumentPickerResponse>
pickDirectory()
Open a system directory picker. Returns a promise that resolves to ({ uri: string }
) of the directory selected by user.
Options
All of the options are optional
allowMultiSelection
:boolean
Whether selecting multiple files is allowed. For pick
, this is false
by default. allowMultiSelection
is false
for pickSingle
and cannot be overridden.
type
:string|Array<string>
The type or types of documents to allow selection of. An array of strings or single string.
- On Android, these are MIME types such as
text/plain
or partial MIME types such asimage/*
. See common MIME types. - On iOS, these must be Apple Uniform Type Identifiers
- If
type
is omitted it will be treated as*/*
orpublic.item
.
[iOS and Android only] copyTo
:"cachesDirectory" | "documentDirectory"
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 (e.g. due to lack of free space), fileCopyUri
will be null
, 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.
On Android, this can be used to obtain local, on-device copy of the file (e.g. if user picks a document from Google Drive, this will download it locally to the phone).
[iOS only] presentationStyle
:'fullScreen' | 'pageSheet' | 'formSheet' | 'overFullScreen'
Controls how the picker is presented, e.g. on an iPad you may want to present it fullscreen. Defaults to pageSheet
.
[iOS only] transitionStyle
:'coverVertical' | 'flipHorizontal' | 'crossDissolve' | 'partialCurl'
Configure the transition style of the picker. Defaults to coverVertical
, when the picker is presented, its view slides up from the bottom of the screen.
[iOS only] mode
:"import" | "open"
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 in-place.
[Windows only] readContent
:boolean
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-fs
on Android and IOS to read the picked file.
Result
The pick
Promise resolves to an array of objects with the following keys.
uri
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.
Please note that you might need to use decodeURIComponent
in order to get the URI in the format you need for further processing, e.g. when using react-native-fs
.
fileCopyUri
If copyTo
option is specified, this will point to a local copy of picked file. Otherwise, this is null
.
type
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.
name
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.
size
The file size of the document. On Android some DocumentProviders may not provide this information for a document.
[Windows only] content
The base64 encoded content of the picked file if the option readContent
was set to true
.
types.*
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).
If you need to provide your own file type filtering:
For Android, see common MIME types.
For iOS Uniform Type Identifiers.
Also, searching Google usually helps.
DocumentPicker.types.allFiles
: All document types, on Android this is*/*
, on iOS ispublic.item
DocumentPicker.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
isCancel(err)
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.
isInProgress(err)
If the user somehow manages to open multiple file pickers (e.g. due the app being unresponsive), then only the picked result from the last opened picker will be considered and the promises from previous opened pickers will be rejected with an error that you can check using DocumentPicker.isInProgress()
.
This behavior might change in future to allow opening only a single picker at a time. The internal logic is currently implemented only on iOS.
[iOS only] releaseSecureAccess(uris: Array<string>)
If mode
is set to open
, iOS is giving you 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.
Example
See the example app in example
folder.
How to upload picked files?
Use blob support that is built into react native - see comment.
If you need to track upload progress, use XMLHttpRequest
see here
Alternatively, use https://github.com/johanneslumpe/react-native-fs
Help wanted: Improvements
- Fix Xcode warning about constraints
- support options for the UIDocumentPickerViewController