A library that provides access to the system's UI for selecting documents from the available providers on the user's device.
GitHub
npm
expo-document-picker
provides access to the system's UI for selecting documents from the available providers on the user's device.
-
npx expo install expo-document-picker
If you are installing this in an existing React Native app, start by installing expo
in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.
You can configure expo-document-picker
using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]
). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use EAS Build, then you'll need to manually configure the package.
If you want to enable iCloud storage features, set the expo.ios.usesIcloudStorage
key to true
in the app config file as specified configuration properties.
Running EAS Build locally will use iOS capabilities signing to enable the required capabilities before building.
{
"expo": {
"plugins": [
[
"expo-document-picker",
{
"iCloudContainerEnvironment": "Production"
}
]
]
}
}
Name | Default | Description |
---|---|---|
iCloudContainerEnvironment | undefined | Only for: iOS Sets the iOS |
Apps that don't use EAS Build and want iCloud storage features must manually configure the iCloud service with CloudKit support for their bundle identifier.
If you enable the iCloud capability through the Apple Developer Console, then be sure to add the following entitlements in your ios/[app]/[app].entitlements
file (where dev.expo.my-app
if your bundle identifier):
<key>com.apple.developer.icloud-container-identifiers</key>
<array>
<string>iCloud.dev.expo.my-app</string>
</array>
<key>com.apple.developer.icloud-services</key>
<array>
<string>CloudDocuments</string>
</array>
<key>com.apple.developer.ubiquity-container-identifiers</key>
<array>
<string>iCloud.dev.expo.my-app</string>
</array>
<key>com.apple.developer.ubiquity-kvstore-identifier</key>
<string>$(TeamIdentifierPrefix)dev.expo.my-app</string>
Apple Developer Console also requires an iCloud Container to be created. When registering the new container, you are asked to provide a description and identifier for the container. You may enter any name under the description. Under the identifier, add iCloud.<your_bundle_identifier>
(same value used for com.apple.developer.icloud-container-identifiers
and com.apple.developer.ubiquity-container-identifiers
entitlements).
expo-file-system
When using expo-document-picker
with expo-file-system
, it's not always possible for the file system to read the file immediately after the expo-document-picker
picks it.
To allow the expo-file-system
to read the file immediately after it is picked, you'll need to ensure that the copyToCacheDirectory
option is set to true
.
import * as DocumentPicker from 'expo-document-picker';
DocumentPicker.getDocumentAsync(namedParameters)
Parameter | Type |
---|---|
namedParameters (optional) | DocumentPickerOptions |
Display the system UI for choosing a document. By default, the chosen file is copied to the app's internal cache directory.
Notes for Web: The system UI can only be shown after user activation (e.g. a
Button
press). Therefore, callinggetDocumentAsync
incomponentDidMount
, for example, will not work as intended. Thecancel
event will not be returned in the browser due to platform restrictions and inconsistencies across browsers.
On success returns a promise that fulfils with DocumentPickerResult
object.
If the user cancelled the document picking, the promise resolves to { type: 'cancel' }
.
DocumentPickerAsset
Name | Type | Description |
---|---|---|
file (optional) | File | Only for: Web
|
lastModified (optional) | number | Timestamp of last document modification. |
mimeType (optional) | string | Document MIME type. |
name | string | Document original name. |
size (optional) | number | Document size in bytes. |
uri | string | An URI to the local document file. |
DocumentPickerCanceledResult
Type representing canceled pick result.
Name | Type | Description |
---|---|---|
assets | null | Always |
canceled | true | Always |
output (optional) | null | Only for: Web Always |
DocumentPickerOptions
Name | Type | Description |
---|---|---|
copyToCacheDirectory (optional) | boolean | If Default: true |
multiple (optional) | boolean | Allows multiple files to be selected from the system UI. Default: false |
type (optional) | string | string[] | The MIME type(s) of the documents that are available
to be picked. It also supports wildcards like Default: '*/*' |
DocumentPickerResult
Literal Type: multiple types
Type representing successful and canceled document pick result.
Acceptable values are: DocumentPickerSuccessResult
| DocumentPickerCanceledResult
DocumentPickerSuccessResult
Type representing successful pick result.
Name | Type | Description |
---|---|---|
assets | DocumentPickerAsset[] | An array of picked assets. |
canceled | false | If asset data have been returned this should always be |
output (optional) | FileList | Only for: Web
|