Import mode

Video introduction

Use import mode when you want to pick a file from the user's device and keep your own copy of it. That means if the original file changes, the copy you have will not change.

If you instead want to keep a reference to the original picked file, use the open mode.

Import mode is the default way to use the module, as in the example below.

picking a file in import mode

import { pick } from '@react-native-documents/picker'
return (
  <Button
    title="single file import"
    onPress={async () => {
      try {
        const [pickResult] = await pick()
        // const [pickResult] = await pick({mode:'import'}) // equivalent
        // do something with the picked file
      } catch (err: unknown) {
        // see error handling
      }
    }}
  />
)

tip

pick(), when it resolves, always returns at least one picked document, and TypeScript won't complain about pickedFile being undefined due to the array destructuring, even with noUncheckedIndexedAccess: true in your tsconfig.json.

How it works

Android

Import mode uses Intent.ACTION_GET_CONTENT internally.

Read more about the difference between the two modes in Android integration guide.

With ACTION_GET_CONTENT, the returned uris are file references transient to your activity's current lifecycle. Regardless of the intent type, it is recommended you import a copy that you can read later, using keepLocalCopy.

iOS

Import mode uses UIDocumentPickerViewController init(forOpeningContentTypes:asCopy:) with asCopy parameter being true.

In import mode, the picker gives you access to a local copy of the documents. The picked documents are temporary files and remain available only for a short time. Officially it's until the application terminates but practically, it appears to be much shorter.

If you want to access a file longer, you have to use keepLocalCopy, or the open mode instead.

Import Options

Name	Type	Description
type?	string | PredefinedFileTypes | (PredefinedFileTypes | string)[]	specify file type(s) that you want to pick. Use types for some predefined values.
allowMultiSelection?	boolean	Whether to allow multiple files to be picked
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	iOS only - Configures the transition style of the picker. Defaults to coverVertical, when the picker is presented, its view slides up from the bottom of the screen.

Import result

The result of the pick function is an array of picked files (the result is the same for both open and import modes). The array has a length of 1 if allowMultiSelection is false (the default), and 1 or more if allowMultiSelection is true.

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 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 have 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 the virtual file can be converted to. Useful for keepLocalCopy. This field is only present 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.