Open mode

Video introduction

In open mode, the returned uris refer directly to the selected documents.

This is particularly useful when you want to read an existing file without making a copy into your app or when you want to open and edit a file in-place (using the Viewer module).

With requestLongTermAccess, your app is granted long-term read access to the file, also possibly with write access (to be clarified in a later docs update).

Picking a file in open mode

import { pick } from '@react-native-documents/picker'

return (
  <Button
    title="open file"
    onPress={async () => {
      try {
        const [result] = await pick({
          mode: 'open',
        })
        console.log(result)
      } catch (err) {
        // see error handling
      }
    }}
  />
)

How it works

Android

Open mode uses Intent.ACTION_OPEN_DOCUMENT internally.

iOS

Open mode uses UIDocumentPickerViewController init(forOpeningContentTypes:asCopy:) internally.

Open Options

Name	Type	Description
mode	'open'	specify that you want the picker to function in the "open" mode.
type?	string | PredefinedFileTypes | (PredefinedFileTypes | string)[]	specify file type(s) that you want to pick. Use types for some predefined values.
requestLongTermAccess?	boolean	Whether to ask for long-term access permissions. False by default.
allowMultiSelection?	boolean	Whether to allow multiple files to be picked. False by default.
allowVirtualFiles?	boolean	Android only - Whether to allow virtual files (such as Google docs or sheets) to be picked. False by default.
presentationStyle?	PresentationStyle	iOS only - Controls how the picker is presented, e.g. on an iPad you may want to present it fullscreen. Defaults to pageSheet.
transitionStyle?	TransitionStyle

Open result

The shape of result is the same for both open and import modes.

note

Many of the fields are nullable because the file metadata might not be available in some cases. While it's unlikely, it can happen - especially on Android - if a user picks a file from a Document Provider that doesn't make the information available.

Each picked file is represented by an object with the following properties:

Name	Type	Description
uri	string	The URI of the picked file. Note that it is encoded, so you might need to decode it for further processing.
name	string | null	The name of the picked file, including the extension. It's very unlikely that it'd be null but in theory, it can happen.
size	number | null	The size of the picked file in bytes.
type	string | null	The MIME type of the picked file.
hasRequestedType	boolean	Android: Some Document Providers on Android (especially those popular in Asia, it seems) do not respect the request for limiting selectable file types. hasRequestedType will be false if the user picked a file that does not match one of the requested types. You need to do your own post-processing and display an error to the user if this is important to your app. Always true on iOS.
error	string | null	Error in case the file metadata could not be obtained.
isVirtual	boolean | null	Android: Whether the file is a virtual file (such as Google docs or sheets). Will be null on pre-Android 7.0 devices. On iOS, it's always false.
convertibleToMimeTypes	string[] | null	Android: The target types to which a virtual file can be converted. Useful for keepLocalCopy. This field is only specified if isVirtual is true, and only on Android 7.0+. Always null on iOS.
nativeType	string | null	The "native" type of the picked file: on Android, this is the MIME type. On iOS, it is the UTType identifier.

Long-term file access

When requestLongTermAccess is set to true, your app will be able to access the file even after the app or device is restarted.

If you've requested long-term access to a directory or file, the response object will contain BookmarkingResponse.

In order to access the same directory or file in the future, you must check bookmarkStatus and store the bookmark opaque string.

Advanced

When you want to access the file later (for example in your own native module), you can use the bookmark to resolve the file uri. See the Document viewer source on how to do it, if you need this.

Request long-term access to a file

import { pick, types } from '@react-native-documents/picker'

return (
  <Button
    title="open pdf file with requestLongTermAccess: true"
    onPress={async () => {
      try {
        const [result] = await pick({
          mode: 'open',
          requestLongTermAccess: true,
          type: [types.pdf],
        })
        if (result.bookmarkStatus === 'success') {
          const bookmarkToStore = {
            fileName: result.name ?? 'unknown name',
            bookmark: result.bookmark,
          }
          localStorage.set('bookmark', JSON.stringify(bookmarkToStore))
        } else {
          console.error(result)
        }
      } catch (err) {
        // see error handling
      }
    }}
  />
)

Releasing Long Term Access

This is an Android-only feature. When you no longer need access to the file or location, you should release the long-term access by calling releaseLongTermAccess. Calling this on iOS will resolve.

See Android documentation for more information.

Releasing (stopping) Secure Access

This is an iOS-only feature. When you no longer need access to the file or location, you should release the secure access by calling releaseSecureAccess. Calling this on Android will resolve.

See iOS documentation for more information.