Guides
Plan-enterprise-icon
Expo Application Services
API Reference

DocumentPicker


expo-document-picker provides access to the system's UI for selecting documents from the available providers on the user's device.

Platform Compatibility

Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb
Status-success-iconStatus-success-iconStatus-success-iconStatus-success-iconStatus-success-icon

Installation

Terminal
npx expo install expo-document-picker

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Configuration in app.json/app.config.js

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.

Triangle-down-icon
Are you using this library in a bare React Native app?

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).

Example app.json with config plugin

If you want to enable iCloud storage features, set the expo.ios.usesIcloudStorage key to true in the Expo 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"
        }
      ]
    ]
  }
}

Configurable properties

NameDefaultDescription
iCloudContainerEnvironmentundefinedOnly for:
Apple-iconiOS

Sets the iOS com.apple.developer.icloud-container-environment entitlement used used for AdHoc iOS builds. Possible values: Development, Production. Learn more.

Using with 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.

API

import * as DocumentPicker from 'expo-document-picker';

Methods

DocumentPicker.getDocumentAsync(namedParameters)

NameTypeDescription
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.

Info-icon

Notes for Web: The system UI can only be shown after user activation (e.g. a Button press). Therefore, calling getDocumentAsync in componentDidMount, for example, will not work as intended. The cancel event will not be returned in the browser due to platform restrictions and inconsistencies across browsers.

  • Undo-iconPromise<DocumentResult>

On success returns a promise that fulfils with DocumentResult object.

If the user cancelled the document picking, the promise resolves to { type: 'cancel' }.

Types

DocumentPickerOptions

NameTypeDescription
copyToCacheDirectory
(optional)
boolean

If true, the picked file is copied to FileSystem.CacheDirectory, which allows other Expo APIs to read the file immediately. This may impact performance for large files, so you should consider setting this to false if you expect users to pick particularly large files and your app does not need immediate read access.

Default: true
multiple
(optional)
booleanOnly for:
At-sign-iconWeb

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. Is also supports wildcards like 'image/*' to choose any image. To allow any type of document you can use '*/*'.

Default: '*/*'

DocumentResult

First object represents the result when the document pick has been cancelled. The second one represents the successful document pick result.

NameTypeDescription
type'cancel'

Field indicating that the document pick has been cancelled.


NameTypeDescription
file
(optional)
FileOnly for:
At-sign-iconWeb

File object for the parity with web File API.

lastModified
(optional)
number

Timestamp of last document modification.

mimeType
(optional)
string

Document MIME type.

namestring

Document original name.

output
(optional)
FileList | nullOnly for:
At-sign-iconWeb

FileList object for the parity with web File API.

size
(optional)
number

Document size in bytes.

type'success'

Field indicating that the document pick has been successful.

uristring

An URI to the local document file.

Was this doc helpful?