HomeGuidesReferenceLearn

Expo DocumentPicker

GitHub

npm


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

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

Managed workflow

For iOS, outside of the Expo Go app, the DocumentPicker module requires the iCloud Services Entitlement to work properly. You need to take the following steps:

  • Set the usesIcloudStorage key to true in your app.json as specified configuration properties.
  • You need to enable the iCloud Application Service in your App identifier. This can be done in the detail of your App ID in the Apple Developer interface.
  • Enable iCloud service with CloudKit support, and create an iCloud Container. 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>.

To apply these changes, you have to revoke your existing provisioning profile and use EAS Build to build the app binaries.

Bare workflow

For iOS bare projects, the DocumentPicker module requires the iCloud entitlement to work properly. If your app doesn't have it already, you can add it by opening the project in Xcode and following these steps:

  • In the project, go to the Capabilities tab
  • Set the iCloud switch to on
  • Check the iCloud Documents checkbox

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.

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.

Returns

  • Promise<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:
Web

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

Default: '*/*'

DocumentResult

NameTypeDescription
type'cancel'-

NameTypeDescription
file
(optional)
File-
lastModified
(optional)
number-
mimeType
(optional)
string

Document MIME type.

namestring

Document original name.

output
(optional)
FileList | null-
size
(optional)
number

Document size in bytes.

type'success'-
uristring

An URI to the local document file.