Document Picker API
Type Aliases
BookmarkingResponse
Ƭ BookmarkingResponse: { bookmark
: string
; bookmarkStatus
: "success"
} | { bookmarkError
: string
; bookmarkStatus
: "error"
}
If you've requested long-term access to a directory or file, this object will be returned in the response.
In order to access the same directory or file in the future, you must store the bookmark
opaque string,
and then pass it to the document viewer if you want to preview the file.
See the Document viewer source on how to retrieve the file from the bookmark, if you need to do that (advanced use case).
FileToCopy
Ƭ FileToCopy: Object
Parameter of keepLocalCopy. Object type representing the file(s) whose copy should be kept in the app's storage.
Type declaration
Name | Type | Description |
---|---|---|
convertVirtualFileToType? | string | Only for Android virtual files: the type of the file to export to. For example, application/pdf or text/plain . Use one of the values from convertibleToMimeTypes from the response of the pick() method: DocumentPickerResponse. |
fileName | string | the name of the resulting file, with the file extension. You can use the name field from the response of the pick() method. Example: someFile.pdf |
uri | string | The uri to keep a local copy of. This would be a content:// uri (Android), or a file:// uri (iOS) that the user has previously picked. |
IsKnownTypeOptions
Ƭ IsKnownTypeOptions: Object
Type declaration
Name | Type | Description |
---|---|---|
kind | "UTType" | "mime" | "extension" | the kind of value you're passing |
value | string | the value you're checking, for example: application/pdf, com.adobe.pdf, pdf |
IsKnownTypeResponse
Ƭ IsKnownTypeResponse: Object
The result of calling isKnownType
Type declaration
Name | Type | Description |
---|---|---|
UTType | string | null | the UTType identifier for the given value, if any |
isKnown | boolean | On iOS, this is true if the type is known to the device. That means it can be used with the document picker to filter what files can be picked. On Android, this is true if the internal mime type database contains the given value. |
mime | string | null | the mime type for the given value, if any |
preferredFilenameExtension | string | null | the preferred filename extension for the given value, if any |
KeepLocalCopyOptions
Ƭ KeepLocalCopyOptions: Object
options for keepLocalCopy
Type declaration
Name | Type |
---|---|
destination | "cachesDirectory" | "documentDirectory" |
files | NonEmptyArray <FileToCopy > |
KeepLocalCopyResponse
Ƭ KeepLocalCopyResponse: NonEmptyArray
<LocalCopyResponse
>
Result of the call to keepLocalCopy. Please note the promise always resolves, even if there was an error processing any uri(s) (as indicated by the status
field, and copyError
field).
LocalCopyResponse
Ƭ LocalCopyResponse: { localUri
: string
; sourceUri
: string
; status
: "success"
} | { copyError
: string
; sourceUri
: string
; status
: "error"
}
Indicates, for each Uri that was passed to keepLocalCopy, whether the local copy was successfully created or not.
If the copy was successful, the status field is success
and localUri
contains the local Uri.
If the copy was not successful, the status field is error
and copyError
field contains the error message.
PredefinedFileTypes
Ƭ PredefinedFileTypes: Flatten
<AllMimeTypes
> | AllAppleUTIs
You'd rarely use this type directly.
It represents the predefined file types which are exported as types
and can be used to limit the kinds of files that can be picked.
Example
import {
pick,
types,
} from '@react-native-documents/picker'
// ...
const result = await pick({
type: [types.pdf, types.docx],
})
PresentationStyle
Ƭ PresentationStyle: "fullScreen"
| "pageSheet"
| "formSheet"
| "overFullScreen"
| undefined
iOS only. Configure the presentation style of the picker.
TransitionStyle
Ƭ TransitionStyle: "coverVertical"
| "flipHorizontal"
| "crossDissolve"
| "partialCurl"
| undefined
iOS only. Configure the transition style of the picker.
Variables
errorCodes
• Const
errorCodes: Readonly
<{ IN_PROGRESS
: "ASYNC_OP_IN_PROGRESS"
; OPERATION_CANCELED
: "OPERATION_CANCELED"
; UNABLE_TO_OPEN_FILE_TYPE
: "UNABLE_TO_OPEN_FILE_TYPE"
}>
Error codes that can be returned by the module, and are available on the code
property of the error.
Example
const handleError = (err: unknown) => {
if (isErrorWithCode(err)) {
switch (err.code) {
case errorCodes.IN_PROGRESS:
...
break
case errorCodes.UNABLE_TO_OPEN_FILE_TYPE:
...
break
case errorCodes.OPERATION_CANCELED:
// ignore
break
default:
console.error(err)
}
} else {
console.error(err)
}
}
Functions
isErrorWithCode
▸ isErrorWithCode(error
): error is NativeModuleError
TypeScript helper to check if an object has the code
property.
This is used to avoid as
casting when you access the code
property on errors returned by the module.
Parameters
Name | Type |
---|---|
error | any |
Returns
error is NativeModuleError
DocumentPicker
isKnownType
▸ isKnownType(options
): IsKnownTypeResponse
Checks if the given value (which can be a file extension, UTType identifier or mime) is known to the system. Also returns the mime type which you can use to filter files on Android.
Parameters
Name | Type |
---|---|
options | IsKnownTypeOptions |
Returns
keepLocalCopy
▸ keepLocalCopy(options
): Promise
<KeepLocalCopyResponse
>
Makes the file available in the app's storage. The behavior is different on iOS and Android, and for simple use cases (such as uploading file to remote server), you may not need to call this method at all.
On Android, it can be used to "convert" a content://
Uri into a local file. It also "exports" virtual files (such as Google docs or sheets) into local files.
However, note that for some use cases, such as uploading the picked file to a server, you may not need to call keepLocalCopy
at all. React Native's TODO can handle content://
uris.
Parameters
Name | Type |
---|---|
options | KeepLocalCopyOptions |
Returns
Promise
<KeepLocalCopyResponse
>
pick
▸ pick<O
>(options?
): PickResponse
<O
>
The method for picking a file, both for import
and open
modes.
For result types, see DocumentPickerResponse or DocumentPickerResponseOpenLongTerm.
For options, see DocumentPickerOptionsImport, DocumentPickerOptionsOpenOnce or DocumentPickerOptionsOpenLongTerm.
Type parameters
Name | Type |
---|---|
O | extends DocumentPickerOptions |
Parameters
Name | Type |
---|---|
options? | O |
Returns
PickResponse
<O
>
pickDirectory
▸ pickDirectory<O
>(options?
): PickDirectoryResponse
<O
>
Opens a directory picker.
Type parameters
Name | Type |
---|---|
O | extends DirectoryPickerOptions |
Parameters
Name | Type |
---|---|
options? | O |
Returns
pick() types
DocumentPickerOptionsBase
Ƭ DocumentPickerOptionsBase: Object
Base options object for the document picker. You'd rarely use this type directly, but instead use one of
DocumentPickerOptionsImport, DocumentPickerOptionsOpenOnce or DocumentPickerOptionsOpenLongTerm
which extend this type
Type declaration
Name | Type | Description |
---|---|---|
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 | 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. |
type? | string | PredefinedFileTypes | (PredefinedFileTypes | string )[] | specify file type(s) that you want to pick. Use types for some predefined values. |
DocumentPickerOptionsImport
Ƭ DocumentPickerOptionsImport: DocumentPickerOptionsBase
& { mode?
: "import"
; requestLongTermAccess?
: never
}
Present the document picker in import mode.
DocumentPickerOptionsOpenLongTerm
Ƭ DocumentPickerOptionsOpenLongTerm: DocumentPickerOptionsBase
& { mode
: "open"
; requestLongTermAccess
: true
}
Present the document picker in open mode, with long-term permissions to access the opened file.
DocumentPickerOptionsOpenOnce
Ƭ DocumentPickerOptionsOpenOnce: DocumentPickerOptionsBase
& { mode
: "open"
; requestLongTermAccess?
: false
}
Present the document picker in open mode, with permissions to access the file for a limited time (until the app terminates).
DocumentPickerResponse
Ƭ DocumentPickerResponse: Object
Type declaration
Name | Type | Description |
---|---|---|
convertibleToMimeTypes | VirtualFileMeta [] | 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. |
error | string | null | Error in case the file metadata could not be obtained. |
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. |
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 . |
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. |
nativeType | string | null | The "native" type of the picked file: on Android, this is the MIME type. On iOS, it is the UTType identifier. |
size | number | null | The size of the picked file in bytes. |
type | string | null | The MIME type of the picked file. |
uri | string | The URI of the picked file. This is a content:// uri (Android), or a file:// uri (iOS). |
DocumentPickerResponseOpenLongTerm
Ƭ DocumentPickerResponseOpenLongTerm: DocumentPickerResponse
& BookmarkingResponse
The result of calling pick with mode: 'open'
and requestLongTermAccess: true
VirtualFileMeta
Ƭ VirtualFileMeta: Object
Type declaration
Name | Type | Description |
---|---|---|
extension | string | null | The registered extension for the given MIME type. Note that some MIME types map to multiple extensions. This call will return the most common extension for the given MIME type. Example: pdf |
mimeType | string | the MIME type of the file. This is necessary to export the virtual file to a local file. Example: application/pdf |
pickDirectory() types
DirectoryPickerOptions
Ƭ DirectoryPickerOptions: DirectoryPickerOptionsBase
& { requestLongTermAccess
: boolean
}
Options for pickDirectory.
DirectoryPickerOptionsBase
Ƭ DirectoryPickerOptionsBase: Object
Base options object for the directory picker. They only slightly influence the appearance of the picker modal on iOS. You'd rarely use this type directly, but instead use DirectoryPickerOptions
which extend this type
Type declaration
Name | Type | Description |
---|---|---|
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. |
DirectoryPickerResponse
Ƭ DirectoryPickerResponse: Object
This object represents the response from the directory picker, when long-term access was not requested.
Type declaration
Name | Type | Description |
---|---|---|
uri | string | The directory selected by user |
DirectoryPickerResponseLongTerm
Ƭ DirectoryPickerResponseLongTerm: DirectoryPickerResponse
& BookmarkingResponse
This object represents the response from the directory picker, when long-term access was requested.
PickDirectoryResponse
Ƭ PickDirectoryResponse<O
>: Promise
<O
extends DirectoryPickerOptionsLongTerm
? DirectoryPickerResponseLongTerm
: DirectoryPickerResponse
>
You likely won't use this type directly, but instead use DirectoryPickerResponse or DirectoryPickerResponseLongTerm.
Type parameters
Name | Type |
---|---|
O | extends DirectoryPickerOptions |