Import mode

Video introduction

Use import mode when you want to pick a file (from the device, cloud storage, etc.) 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.

Next steps

After importing a file, it's likely that you'll want to work with a local copy of it: see keeping a local copy. This is because on Android, the picked files may point to resources that are not present on the device but in some cloud location. On iOS, the picked files are always downloaded by the system, but they are stored as temporary files that are only available for a short time.

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

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