-
Notifications
You must be signed in to change notification settings - Fork 0
/
search-doc.json
1 lines (1 loc) · 63.4 KB
/
search-doc.json
1
{"searchDocs":[{"title":"document-viewer API","type":0,"sectionRef":"#","url":"/docs/doc-viewer-api","content":"","keywords":"","version":null},{"title":"Type Aliases","type":1,"pageTitle":"document-viewer API","url":"/docs/doc-viewer-api#type-aliases","content":" ","version":null,"tagName":"h2"},{"title":"BaseOptions","type":1,"pageTitle":"document-viewer API","url":"/docs/doc-viewer-api#baseoptions","content":" BaseOptions: {grantPermissions: "read" | "write";headerTitle: string;mimeType: string;presentationStyle: PresentationStyle; } Type declaration Name\tType\tDescriptiongrantPermissions?\t"read" | "write"\tAndroid only: The type of permission to grant to the receiving app that will open the document. This only has effect if you're viewing a file that lives in the app's sandboxed storage. headerTitle?\tstring\tiOS only: The title to display in the header of the document viewer. If not provided, the filename will be used. mimeType?\tstring\tOptional, but recommended: the mimetype of the document. This will help the Android OS to find the right app(s) to open the document. presentationStyle?\tPresentationStyle\tiOS only - Controls how the picker is presented, e.g. on an iPad you may want to present it fullscreen. Defaults to pageSheet. ","version":null,"tagName":"h3"},{"title":"OptionsViewBookmark","type":1,"pageTitle":"document-viewer API","url":"/docs/doc-viewer-api#optionsviewbookmark","content":" OptionsViewBookmark: BaseOptions & {bookmark: string; } BaseOptions with the bookmark data from the DocumentPicker module. Obtain the bookmark using the "open" mode, with requestLongTermAccess flag set to true. A bookmark enables long-term access to a file. Type declaration Name\tType\tDescriptionbookmark\tstring\tbookmark data from the DocumentPicker module. Obtain it using the "open" mode, with requestLongTermAccess flag set to true. A bookmark allows a long-term permission to access a file. ","version":null,"tagName":"h3"},{"title":"OptionsViewUri","type":1,"pageTitle":"document-viewer API","url":"/docs/doc-viewer-api#optionsviewuri","content":" OptionsViewUri: BaseOptions & {uri: string; } BaseOptions with the uri of the document to view Type declaration Name\tType\tDescriptionuri\tstring\tThe uri of the document to view ","version":null,"tagName":"h3"},{"title":"PresentationStyle","type":1,"pageTitle":"document-viewer API","url":"/docs/doc-viewer-api#presentationstyle","content":" PresentationStyle: "fullScreen" | "pageSheet" | "formSheet" | "overFullScreen" | undefined iOS only. Configure the presentation style of the picker. ","version":null,"tagName":"h3"},{"title":"ViewDocumentOptions","type":1,"pageTitle":"document-viewer API","url":"/docs/doc-viewer-api#viewdocumentoptions","content":" ViewDocumentOptions: OptionsViewBookmark | OptionsViewUri options for viewing a document If you're trying to open a file that you have long-term permission to access, you should use the bookmark option (provided by the DocumentPicker module). ","version":null,"tagName":"h3"},{"title":"Functions","type":1,"pageTitle":"document-viewer API","url":"/docs/doc-viewer-api#functions","content":" ","version":null,"tagName":"h2"},{"title":"viewDocument()","type":1,"pageTitle":"document-viewer API","url":"/docs/doc-viewer-api#viewdocument","content":" viewDocument(data: ViewDocumentOptions): Promise<null> Parameters Parameter\tTypedata\tViewDocumentOptions Returns Promise<null> ","version":null,"tagName":"h3"},{"title":"Installation","type":0,"sectionRef":"#","url":"/docs/install","content":"","keywords":"","version":null},{"title":"Premium Version","type":1,"pageTitle":"Installation","url":"/docs/install#premium-version","content":" This version offers many improvements over the public version. Full list of changes is here. To mention a few: ✅ New: saveDocuments function ✅ New: isKnownType utility ✅ New: open mode support for both platforms ✅ New: long-term file access permissions on both platforms ✅ New: keepLocalCopy function that separates picking a file and copying it to a local directory, which makes your app more responsive. ... and more Your support enables continued maintenance and development of the module. Thank you! ❤️ ","version":null,"tagName":"h3"},{"title":"Public Version","type":1,"pageTitle":"Installation","url":"/docs/install#public-version","content":" Available on the public npm registry, this version does not include the new features, updates and improvements found in the premium version. ","version":null,"tagName":"h3"},{"title":"Accessing the premium version","type":1,"pageTitle":"Installation","url":"/docs/install#accessing-the-premium-version","content":" Access is provided via GitHub Sponsors: upon sponsoring you will get access to the private packages and to the private monorepo with the sources and examples (please use specifically the tiers that mention this package!). Three steps are needed to access the premium packages, which are hosted on GitHub npm packages registry. Become a sponsor and accept private repository invitation - it takes just a few clicks. Obtain here a Personal Access Token with packages:read permission. Set up your package manager so that it fetches the packages from the GH packages registry. In this example, we're using an NPM_TOKEN environment variable. npm / yarn v1yarn v3+ create a .npmrc file in your project root with the following content: //npm.pkg.github.com/:_authToken=${NPM_TOKEN} @react-native-documents:registry=https://npm.pkg.github.com/ If you use another package manager (such as bun), please refer to its documentation on how to set up a custom registry. ","version":null,"tagName":"h2"},{"title":"Installing","type":1,"pageTitle":"Installation","url":"/docs/install#installing","content":" For sponsorsPublic package yarn add @react-native-documents/picker yarn add @react-native-documents/viewer ","version":null,"tagName":"h2"},{"title":"Setting up","type":1,"pageTitle":"Installation","url":"/docs/install#setting-up","content":" warning The premium document picker package requires iOS 14 or later. If you use Expo, use Expo build properties to update the deploymentTarget to 14. In regular React Native projects, update the settings in Xcode. ","version":null,"tagName":"h2"},{"title":"Expo","type":1,"pageTitle":"Installation","url":"/docs/install#expo","content":" info This package cannot be used in "Expo Go" because it requires custom native code. However, you can add custom native code to Expo through a development build. That is the approach taken below. # install the package first # Build the app locally expo prebuild --clean expo run:ios expo run:android ","version":null,"tagName":"h3"},{"title":"React Native","type":1,"pageTitle":"Installation","url":"/docs/install#react-native","content":" Install the package and then run pod install from the ios directory. Then rebuild your project with Xcode. The packages were tested with RN 0.74 but they most likely support older RN versions as well, all the way to 0.60. If you're using the New Architecture, you need to be on React Native 0.72 or higher. ","version":null,"tagName":"h3"},{"title":"Error handling","type":0,"sectionRef":"#","url":"/docs/sponsor-only/errors","content":"","keywords":"","version":null},{"title":"Error codes","type":1,"pageTitle":"Error handling","url":"/docs/sponsor-only/errors#error-codes","content":" Both picker and viewer expose the errorCodes object which contains an object of possible error codes that can be returned by the native module. Error codes are useful when determining which kind of error has occurred during the picking or viewing process. Error Code Key\tDescriptionIN_PROGRESS\tThis is rather a warning, that happens when you invoke an operation (e.g. pick) while a previous one has not finished yet. For example: if you call pick() quickly twice in a row, 2 calls to pick() in the native module will be done. The first call will open the native document picker and user action will be expected. The promise from the second call to pick will be rejected with this error. Later, the first promise will resolve (or reject) with the actual files that the user has selected. Only one document picker window will be presented to the user. The reason the module explicitly rejects "duplicated" calls is to avoid memory leaks and to inform you that something probably isn't done right. UNABLE_TO_OPEN_FILE_TYPE\tWhen you try to use the picker or viewer using a configuration that system cannot comply with. On Android, this corresponds to ActivityNotFoundException. On iOS, this only happens in the Viewer module when you attempt to preview a file that's not supported by the QuickLook framework. OPERATION_CANCELED\tWhen user cancels the operation note In a future release, OPERATION_CANCELED will be replaced with a more streamlined cancellation handling. I'm keeping it now to make migration easier. error-handling.ts import { errorCodes } from '@react-native-documents/picker' // or import { errorCodes } from '@react-native-documents/viewer' const handleError = (err: unknown) => { if (isErrorWithCode(err)) { switch (err.code) { case errorCodes.IN_PROGRESS: console.warn('user attempted to present a picker, but a previous one was already presented') break case errorCodes.UNABLE_TO_OPEN_FILE_TYPE: setError('unable to open file type') break case errorCodes.OPERATION_CANCELED: // ignore break default: setError(String(err)) console.error(err) } } else { setError(String(err)) } } ","version":null,"tagName":"h3"},{"title":"isErrorWithCode(value)","type":1,"pageTitle":"Error handling","url":"/docs/sponsor-only/errors#iserrorwithcodevalue","content":" TypeScript helper to check if the passed parameter is an instance of Error which has the code property. All errors thrown by the picker and viewer native modules have the code property, which contains a value from errorCodes or some other string for the less-usual errors. isErrorWithCode can be used to avoid as casting when you want to access the code property on errors returned by the module. import { pick, isErrorWithCode } from '@react-native-documents/picker' try { const [pickResult] = await pick() // do something with pickResult } catch (error) { if (isErrorWithCode(error)) { // here you can safely read `error.code` and TypeScript will know that it has a value } else { // this error does not have a `code`, and does not come from the native module } } ","version":null,"tagName":"h3"},{"title":"Introduction","type":0,"sectionRef":"#","url":"/docs/sponsor-only/intro","content":"","keywords":"","version":null},{"title":"What's new in the premium packages?","type":1,"pageTitle":"Introduction","url":"/docs/sponsor-only/intro#whats-new-in-the-premium-packages","content":" There's the improved (list of changes below) picker package (called @react-native-documents/picker) with api that's very similar to the original. Secondly, there's the completely new @react-native-documents/viewer package which is designed to work well together with picker. ","version":null,"tagName":"h2"},{"title":"TypeScript","type":1,"pageTitle":"Introduction","url":"/docs/sponsor-only/intro#typescript","content":" improved type definitions that make use of Discriminated Unions and other goodies so that you don't try to read fields that are not there, and nullable fields are also reduced. (You can use vanilla JS too if you like.).mocks for testingpickSingle method was replaced for more streamlined const [result] = pick() ","version":null,"tagName":"h3"},{"title":"iOS","type":1,"pageTitle":"Introduction","url":"/docs/sponsor-only/intro#ios","content":" new: saveDocuments functionnew: isKnownType utilitynew: support for long-term file access permissions - across app and even device reboots! (requestLongTermAccess)new: keepLocalCopy function that separates picking a file and copying it to a local directory. This makes your app more responsive: previously you'd use the copyTo option and before the resulting Promise resolved, you needed to wait not only for user to pick the file, but also for the file to be copied to your app's directory. For large files or with slow network, this could be a problem that you, as a dev don't see, but your users do.improved: the majority of the code is now written in Swift, making code safer and more readable.improved: less use of the main thread.improved: using the new UIDocumentPickerViewController apis instead of those deprecated in iOS 14improved: instead of the old copyTo parameter making unnecessary copies, the new keepLocalCopy function moves the imported file. ","version":null,"tagName":"h3"},{"title":"Android","type":1,"pageTitle":"Introduction","url":"/docs/sponsor-only/intro#android","content":" new: saveDocuments functionnew: support for open modenew: support for long-term file access permissions - across app and even device reboots! (requestLongTermAccess)new: keepLocalCopy function that separates picking a file and copying it to a local directory. This makes your app more responsive: previously you'd use the copyTo option and before the resulting Promise resolved, you needed to wait not only for user to pick the file, but also for the file to be copied to your app's directory. For large files or with slow network, this could be a problem that you, as a dev don't see, but your users do.new: support for virtual filesimproved: deprecated AsyncTask usage was replaced with Kotlin Coroutines.improved: the code is better at operating with I/O, for example buffering is replaced with a potentially much more efficient alternative from java.nioimproved: reading file metadata is more defensive and efficient because only the necessary columns are queried from ContentResolver. The native Android apis are full of calls that can return null or throw so extra care is taken to handle these cases. ","version":null,"tagName":"h3"},{"title":"Windows","type":1,"pageTitle":"Introduction","url":"/docs/sponsor-only/intro#windows","content":" Windows is not supported at the moment. While there is Windows-related code in the public module, it's not maintained and probably does not work. ","version":null,"tagName":"h3"},{"title":"How do I know it works?","type":1,"pageTitle":"Introduction","url":"/docs/sponsor-only/intro#how-do-i-know-it-works","content":" With so many changes, you might wonder if the new package is stable - especially with Android because... well, we know Android 😜. To prove the new code is solid, I have written an e2e test suite using Appium that covers the majority of the features: import modeopen modeviewing files, including long-term permissions The test suite focuses on Android, and was executed on real devices from Samsung, Google and Huawei, with Android versions ranging between 8 and 14. iOS tests were done manually on a real device with iOS 17. As a result, I have greater confidence in the new package than in the old one! ","version":null,"tagName":"h3"},{"title":"Why do I ask for sponsorship?","type":1,"pageTitle":"Introduction","url":"/docs/sponsor-only/intro#why-do-i-ask-for-sponsorship","content":" I (vonovak) have been maintaining the original react-native-document-picker package more or less since 2020. The package has been used by thousands of devs, but I could see that there was a lot to improve. In January 2024 I decided to rewrite the package from scratch and make it better! The new package has a new name: @react-native-documents/picker and is hosted on the GitHub packages npm registry. While I was at it, I also created a new viewer package. How to make OSS sustainable? My take is this: rather than asking for support, I provide full-featured packages and ask for a fee in return. I believe that the new packages are worth it. Feel free to read more in my GitHub Sponsors profile. ","version":null,"tagName":"h2"},{"title":"Migrating from the old package","type":1,"pageTitle":"Introduction","url":"/docs/sponsor-only/intro#migrating-from-the-old-package","content":" See the 3-step migration guide. ","version":null,"tagName":"h2"},{"title":"document-picker API","type":0,"sectionRef":"#","url":"/docs/doc-picker-api","content":"","keywords":"","version":null},{"title":"Type Aliases","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#type-aliases","content":" ","version":null,"tagName":"h2"},{"title":"BookmarkingResponse","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#bookmarkingresponse","content":" 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). ","version":null,"tagName":"h3"},{"title":"FileToCopy","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#filetocopy","content":" FileToCopy: {convertVirtualFileToType: string;fileName: string;uri: string; } Parameter of keepLocalCopy. Object type representing the file(s) whose copy should be kept in the app's storage. Type declaration Name\tType\tDescriptionconvertVirtualFileToType?\tstring\tOnly 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\tstring\tThe 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\tstring\tThe 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. ","version":null,"tagName":"h3"},{"title":"IsKnownTypeOptions","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#isknowntypeoptions","content":" IsKnownTypeOptions: {kind: "UTType" | "mimeType" | "extension";value: string; } Type declaration Name\tType\tDescriptionkind\t"UTType" | "mimeType" | "extension"\tthe kind of value you're passing value\tstring\tthe value you're checking, for example: application/pdf, com.adobe.pdf, pdf ","version":null,"tagName":"h3"},{"title":"IsKnownTypeResponse","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#isknowntyperesponse","content":" IsKnownTypeResponse: {isKnown: boolean;mimeType: string | null;preferredFilenameExtension: string | null;UTType: string | null; } The result of calling isKnownType Type declaration Name\tType\tDescriptionisKnown\tboolean\tOn 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. mimeType\tstring | null\tthe mime type for the given value, if any preferredFilenameExtension\tstring | null\tthe preferred filename extension for the given value, if any UTType\tstring | null\tthe UTType identifier for the given value, if any ","version":null,"tagName":"h3"},{"title":"KeepLocalCopyOptions","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#keeplocalcopyoptions","content":" KeepLocalCopyOptions: {destination: "cachesDirectory" | "documentDirectory";files: NonEmptyArray<FileToCopy>; } options for keepLocalCopy Type declaration Name\tTypedestination\t"cachesDirectory" | "documentDirectory" files\tNonEmptyArray<FileToCopy> ","version":null,"tagName":"h3"},{"title":"KeepLocalCopyResponse","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#keeplocalcopyresponse","content":" 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). ","version":null,"tagName":"h3"},{"title":"LocalCopyResponse","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#localcopyresponse","content":" 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. ","version":null,"tagName":"h3"},{"title":"PredefinedFileTypes","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#predefinedfiletypes","content":" 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], }) ","version":null,"tagName":"h3"},{"title":"PresentationStyle","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#presentationstyle","content":" PresentationStyle: "fullScreen" | "pageSheet" | "formSheet" | "overFullScreen" | undefined iOS only. Configure the presentation style of the picker. ","version":null,"tagName":"h3"},{"title":"ReleaseLongTermAccessResult","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#releaselongtermaccessresult","content":" ReleaseLongTermAccessResult: ({status: "success";uri: string; } | {errorMessage: string;status: "error";uri: string; })[] For each uri whose release was requested, the result will contain an object with the uri and a status. ","version":null,"tagName":"h3"},{"title":"TransitionStyle","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#transitionstyle","content":" TransitionStyle: "coverVertical" | "flipHorizontal" | "crossDissolve" | "partialCurl" | undefined iOS only. Configure the transition style of the picker. ","version":null,"tagName":"h3"},{"title":"Variables","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#variables","content":" ","version":null,"tagName":"h2"},{"title":"errorCodes","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#errorcodes","content":" 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. Type declaration Name\tTypeIN_PROGRESS\t"ASYNC_OP_IN_PROGRESS" OPERATION_CANCELED\t"OPERATION_CANCELED" UNABLE_TO_OPEN_FILE_TYPE\t"UNABLE_TO_OPEN_FILE_TYPE" 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) } } ","version":null,"tagName":"h3"},{"title":"Functions","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#functions","content":" ","version":null,"tagName":"h2"},{"title":"isErrorWithCode()","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#iserrorwithcode","content":" isErrorWithCode(error: any): 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 Parameter\tTypeerror\tany Returns error is NativeModuleError ","version":null,"tagName":"h3"},{"title":"releaseLongTermAccess()","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#releaselongtermaccess","content":" releaseLongTermAccess(uris: string[]): Promise<ReleaseLongTermAccessResult> Android only - Releases long-term access to the given URIs. There's no need to call this method on iOS - there's no iOS equivalent. See Android documentation for more information. Parameters Parameter\tTypeuris\tstring[] Returns Promise<ReleaseLongTermAccessResult> ","version":null,"tagName":"h3"},{"title":"releaseSecureAccess()","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#releasesecureaccess","content":" releaseSecureAccess(uris: string[]): Promise<null> iOS only - Releases (stops) secure access to the given URIs. Use with URIs obtained with Open mode or with the Directory Picker. See iOS documentation for more information. There's no need to call this method on Android - there's no equivalent method on Android. Parameters Parameter\tTypeuris\tstring[] Returns Promise<null> ","version":null,"tagName":"h3"},{"title":"DocumentPicker","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#documentpicker","content":" ","version":null,"tagName":"h2"},{"title":"isKnownType()","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#isknowntype","content":" isKnownType(options: IsKnownTypeOptions): 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 Parameter\tTypeoptions\tIsKnownTypeOptions Returns IsKnownTypeResponse ","version":null,"tagName":"h3"},{"title":"keepLocalCopy()","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#keeplocalcopy","content":" keepLocalCopy(options: KeepLocalCopyOptions): 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 fetch can handle content:// uris. Parameters Parameter\tTypeoptions\tKeepLocalCopyOptions Returns Promise<KeepLocalCopyResponse> ","version":null,"tagName":"h3"},{"title":"pick()","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#pick","content":" pick<O>(options?: O): 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 Type ParameterO extends DocumentPickerOptions Parameters Parameter\tTypeoptions?\tO Returns PickResponse<O> ","version":null,"tagName":"h3"},{"title":"pickDirectory()","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#pickdirectory","content":" pickDirectory<O>(options?: O): PickDirectoryResponse<O> Opens a directory picker. Type Parameters Type ParameterO extends DirectoryPickerOptions Parameters Parameter\tTypeoptions?\tO Returns PickDirectoryResponse<O> ","version":null,"tagName":"h3"},{"title":"saveDocuments()","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#savedocuments","content":" saveDocuments(options: SaveDocumentsOptions): Promise<NonEmptyArray<SaveDocumentsResponse>> The method for opening a "save as" dialog and saving source file(s) to a new location. On Android, only one file can be saved at a time. Parameters Parameter\tTypeoptions\tSaveDocumentsOptions Returns Promise<NonEmptyArray<SaveDocumentsResponse>> ","version":null,"tagName":"h3"},{"title":"pick() types","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#pick-types","content":" ","version":null,"tagName":"h2"},{"title":"DocumentPickerOptionsBase","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#documentpickeroptionsbase","content":" DocumentPickerOptionsBase: {allowMultiSelection: boolean;allowVirtualFiles: boolean;presentationStyle: PresentationStyle;transitionStyle: TransitionStyle;type: string | PredefinedFileTypes | (PredefinedFileTypes | string)[]; } 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\tType\tDescriptionallowMultiSelection?\tboolean\tWhether to allow multiple files to be picked. False by default. allowVirtualFiles?\tboolean\tAndroid only - Whether to allow virtual files (such as Google docs or sheets) to be picked. False by default. presentationStyle?\tPresentationStyle\tiOS only - Controls how the picker is presented, e.g. on an iPad you may want to present it fullscreen. Defaults to pageSheet. transitionStyle?\tTransitionStyle\tiOS 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?\tstring | PredefinedFileTypes | (PredefinedFileTypes | string)[]\tSpecify file type(s) that you want to pick. Use types for some predefined values. ","version":null,"tagName":"h3"},{"title":"DocumentPickerOptionsImport","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#documentpickeroptionsimport","content":" DocumentPickerOptionsImport: DocumentPickerOptionsBase & {mode: "import";requestLongTermAccess: never; } Present the document picker in import mode. Type declaration Name\tTypemode?\t"import" requestLongTermAccess?\tnever ","version":null,"tagName":"h3"},{"title":"DocumentPickerOptionsOpenLongTerm","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#documentpickeroptionsopenlongterm","content":" DocumentPickerOptionsOpenLongTerm: DocumentPickerOptionsBase & {mode: "open";requestLongTermAccess: true; } Present the document picker in open mode, with long-term permissions to access the opened file. Type declaration Name\tTypemode\t"open" requestLongTermAccess\ttrue ","version":null,"tagName":"h3"},{"title":"DocumentPickerOptionsOpenOnce","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#documentpickeroptionsopenonce","content":" 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). Type declaration Name\tTypemode\t"open" requestLongTermAccess?\tfalse ","version":null,"tagName":"h3"},{"title":"DocumentPickerResponse","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#documentpickerresponse","content":" DocumentPickerResponse: {convertibleToMimeTypes: VirtualFileMeta[] | null;error: string | null;hasRequestedType: boolean;isVirtual: boolean | null;name: string | null;nativeType: string | null;size: number | null;type: string | null;uri: string; } Type declaration Name\tType\tDescriptionconvertibleToMimeTypes\tVirtualFileMeta[] | null\tAndroid: 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\tstring | null\tError in case the file metadata could not be obtained. hasRequestedType\tboolean\tAndroid: 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\tboolean | null\tAndroid: 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\tstring | null\tThe name of the picked file, including the extension. It's very unlikely that it'd be null but in theory, it can happen. nativeType\tstring | null\tThe "native" type of the picked file: on Android, this is the MIME type. On iOS, it is the UTType identifier. size\tnumber | null\tThe size of the picked file in bytes. type\tstring | null\tThe MIME type of the picked file. uri\tstring\tThe URI of the picked file. This is a percent-encoded content:// uri (Android), or a file:// uri (iOS). ","version":null,"tagName":"h3"},{"title":"DocumentPickerResponseOpenLongTerm","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#documentpickerresponseopenlongterm","content":" DocumentPickerResponseOpenLongTerm: DocumentPickerResponse & BookmarkingResponse The result of calling pick with mode: 'open' and requestLongTermAccess: true ","version":null,"tagName":"h3"},{"title":"VirtualFileMeta","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#virtualfilemeta","content":" VirtualFileMeta: {extension: string | null;mimeType: string; } Type declaration Name\tType\tDescriptionextension\tstring | null\tThe 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\tstring\tThe MIME type of the file. This is necessary to export the virtual file to a local file. Example: application/pdf ","version":null,"tagName":"h3"},{"title":"pickDirectory() types","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#pickdirectory-types","content":" ","version":null,"tagName":"h2"},{"title":"DirectoryPickerOptions","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#directorypickeroptions","content":" DirectoryPickerOptions: DirectoryPickerOptionsBase & {requestLongTermAccess: boolean; } Options for pickDirectory. Type declaration Name\tTyperequestLongTermAccess\tboolean ","version":null,"tagName":"h3"},{"title":"DirectoryPickerOptionsBase","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#directorypickeroptionsbase","content":" DirectoryPickerOptionsBase: {presentationStyle: PresentationStyle;transitionStyle: TransitionStyle; } 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\tType\tDescriptionpresentationStyle?\tPresentationStyle\tiOS only - Controls how the picker is presented, e.g. on an iPad you may want to present it fullscreen. Defaults to pageSheet. transitionStyle?\tTransitionStyle\tiOS 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. ","version":null,"tagName":"h3"},{"title":"DirectoryPickerResponse","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#directorypickerresponse","content":" DirectoryPickerResponse: {uri: string; } This object represents the response from the directory picker, when long-term access was not requested. Type declaration Name\tType\tDescriptionuri\tstring\tThe (percent-encoded) directory selected by user. ","version":null,"tagName":"h3"},{"title":"DirectoryPickerResponseLongTerm","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#directorypickerresponselongterm","content":" DirectoryPickerResponseLongTerm: DirectoryPickerResponse & BookmarkingResponse This object represents the response from the directory picker, when long-term access was requested. ","version":null,"tagName":"h3"},{"title":"PickDirectoryResponse<O>","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#pickdirectoryresponseo","content":" PickDirectoryResponse<O>: Promise<O extends DirectoryPickerOptionsLongTerm ? DirectoryPickerResponseLongTerm : DirectoryPickerResponse> You likely won't use this type directly, but instead use DirectoryPickerResponse or DirectoryPickerResponseLongTerm. Type Parameters Type ParameterO extends DirectoryPickerOptions ","version":null,"tagName":"h3"},{"title":"saveDocuments() types","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#savedocuments-types","content":" ","version":null,"tagName":"h2"},{"title":"SaveDocumentsOptions","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#savedocumentsoptions","content":" SaveDocumentsOptions: {copy: boolean;fileName: string;mimeType: string;sourceUris: string[]; } Options object for the saveDocuments method. sourceUris is the only required field. Type declaration Name\tType\tDescriptioncopy?\tboolean\tiOS-only: Whether to copy the file to a new location, or move it (default). On Android, file is always copied. fileName?\tstring\tAndroid-only: The suggested title of the file to be stored, which will be pre-filled in the UI. On iOS, the target name is taken from the source uri, and is changeable only when exactly one file is being saved. mimeType?\tstring\tAndroid-only: The MIME type of the file to be stored. It is recommended to provide this value, otherwise the system will try to infer it from the sourceUri using ContentResolver. sourceUris\tstring[]\tThe source URIs of the files to save, percentage-encoded. Android only allows to save one file at a time, iOS allows multiple. ","version":null,"tagName":"h3"},{"title":"SaveDocumentsResponse","type":1,"pageTitle":"document-picker API","url":"/docs/doc-picker-api#savedocumentsresponse","content":" SaveDocumentsResponse: {error: string | null;name: string | null;uri: string; } The result of calling saveDocuments. It is very unlikely that the metadata fields would be null, but in theory, it can happen. Type declaration Name\tType\tDescriptionerror\tstring | null\tError in case the file could not be written or some metadata could not be obtained. name\tstring | null\tThe name of the file that user entered, including extension. uri\tstring\tThe target URI - the one user saved to. This is a percent-encoded content:// uri (Android), or a file:// uri (iOS). ","version":null,"tagName":"h3"},{"title":"Jest module mocks","type":0,"sectionRef":"#","url":"/docs/sponsor-only/jest-mocks","content":"Jest module mocks You will need to mock the functionality of the native modules once you require them from your test files - otherwise you'll get this error. The packages provide Jest mocks that you can add to the setupFiles array in the Jest config. By default, the mocks behave as if the calls were successful and return mock document data. jest.config { "setupFiles": [ "./node_modules/@react-native-documents/picker/jest/build/jest/setup.js", "./node_modules/@react-native-documents/viewer/jest/build/jest/setup.js" ] } ","keywords":"","version":null},{"title":"Other libraries","type":0,"sectionRef":"#","url":"/docs/sponsor-only/other-libs","content":"","keywords":"","version":null},{"title":"react-native-theme-control","type":1,"pageTitle":"Other libraries","url":"/docs/sponsor-only/other-libs#react-native-theme-control","content":" Natively control react native application theme at runtime and persist it for the next app start. ","version":null,"tagName":"h3"},{"title":"react-navigation-header-buttons","type":1,"pageTitle":"Other libraries","url":"/docs/sponsor-only/other-libs#react-navigation-header-buttons","content":" Easily render header buttons for react-navigation. ","version":null,"tagName":"h3"},{"title":"react-to-imperative","type":1,"pageTitle":"Other libraries","url":"/docs/sponsor-only/other-libs#react-to-imperative","content":" Convert React (Native) components for imperative use. ","version":null,"tagName":"h3"},{"title":"react-native-datetimepicker","type":1,"pageTitle":"Other libraries","url":"/docs/sponsor-only/other-libs#react-native-datetimepicker","content":" React Native date & time picker component for iOS and Android. ","version":null,"tagName":"h3"},{"title":"JS-lingui","type":1,"pageTitle":"Other libraries","url":"/docs/sponsor-only/other-libs#js-lingui","content":" A readable, automated, and optimized internationalization for JavaScript. ","version":null,"tagName":"h3"},{"title":"react-native-google-signin","type":1,"pageTitle":"Other libraries","url":"/docs/sponsor-only/other-libs#react-native-google-signin","content":" Google Sign In for React Native. ","version":null,"tagName":"h3"},{"title":"Migrating from the old document-picker","type":0,"sectionRef":"#","url":"/docs/sponsor-only/migration","content":"","keywords":"","version":null},{"title":"Migrating your code","type":1,"pageTitle":"Migrating from the old document-picker","url":"/docs/sponsor-only/migration#migrating-your-code","content":" Good news: You need to make only a few changes: update import statements import { ... } from 'react-native-document-picker' becomes import { ... } from '@react-native-documents/picker' remove pickSingle Replace pickSingle with pick: const result = await pickSingle(options) becomes: const [result] = await pick(options) replace copyTo with keepLocalCopy This change makes your app more responsive: previously you'd use the copyTo option and before the returned Promise resolved, you needed to wait not only for the user to pick the file, but also for the file to be copied to your app's directory. For large files or with slow network, this could be a problem that you, as a dev don't see, but your users do. const localCopy = await pick({ copyTo: 'documentDirectory', }) becomes const [file] = await pick() const [localCopy] = await keepLocalCopy({ files: [ { uri: file.uri, fileName: file.name ?? 'fallbackName', }, ], destination: 'documentDirectory', }) ","version":null,"tagName":"h3"},{"title":"Directory Picker","type":0,"sectionRef":"#","url":"/docs/sponsor-only/picker/directory-picker","content":"","keywords":"","version":null},{"title":"How it works","type":1,"pageTitle":"Directory Picker","url":"/docs/sponsor-only/picker/directory-picker#how-it-works","content":" AndroidiOS Open mode uses Intent.ACTION_OPEN_DOCUMENT_TREE internally. ","version":null,"tagName":"h3"},{"title":"Writing to the directory location","type":1,"pageTitle":"Directory Picker","url":"/docs/sponsor-only/picker/directory-picker#writing-to-the-directory-location","content":" In order to write to the user-selected location, this approach needs to be used: on Android: https://stackoverflow.com/a/61120265on iOS: docs ","version":null,"tagName":"h3"},{"title":"Releasing Long Term Access","type":1,"pageTitle":"Directory Picker","url":"/docs/sponsor-only/picker/directory-picker#releasing-long-term-access","content":" 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. ","version":null,"tagName":"h3"},{"title":"Releasing (stopping) Secure Access","type":1,"pageTitle":"Directory Picker","url":"/docs/sponsor-only/picker/directory-picker#releasing-stopping-secure-access","content":" 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. ","version":null,"tagName":"h3"},{"title":"Android Usage Notes","type":0,"sectionRef":"#","url":"/docs/sponsor-only/picker/integrating-on-android","content":"","keywords":"","version":null},{"title":"Screenshots","type":1,"pageTitle":"Android Usage Notes","url":"/docs/sponsor-only/picker/integrating-on-android#screenshots","content":" Sometimes pictures are worth a thousand words. Here are some example screenshots of the Open and Import modes on Android. Notice that in the "Import Mode (unrestricted file types)" case, the list is taller than the screen. Open Mode (unrestricted file types)\tImport Mode (unrestricted file types) Open Mode (restricted to picking pdf)\tImport Mode (restricted to picking pdf) ","version":null,"tagName":"h3"},{"title":"Resources","type":1,"pageTitle":"Android Usage Notes","url":"/docs/sponsor-only/picker/integrating-on-android#resources","content":" Assorted links to relevant resources: Intent.ACTION_GET_CONTENT (used in Import mode)Intent.ACTION_OPEN_DOCUMENT (used in Open mode)Open a specific type of fileWhat is the real difference between ACTION_GET_CONTENT and ACTION_OPEN_DOCUMENT?note in "Write a client app" ","version":null,"tagName":"h3"},{"title":"Import mode","type":0,"sectionRef":"#","url":"/docs/sponsor-only/picker/import-mode","content":"","keywords":"","version":null},{"title":"Next steps","type":1,"pageTitle":"Import mode","url":"/docs/sponsor-only/picker/import-mode#next-steps","content":" 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. ","version":null,"tagName":"h3"},{"title":"How it works","type":1,"pageTitle":"Import mode","url":"/docs/sponsor-only/picker/import-mode#how-it-works","content":" AndroidiOS 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. ","version":null,"tagName":"h3"},{"title":"Import Options","type":1,"pageTitle":"Import mode","url":"/docs/sponsor-only/picker/import-mode#import-options","content":" Name\tType\tDescriptiontype?\tstring | PredefinedFileTypes | (PredefinedFileTypes | string)[]\tspecify file type(s) that you want to pick. Use types for some predefined values. allowMultiSelection?\tboolean\tWhether to allow multiple files to be picked allowVirtualFiles?\tboolean\tAndroid only - Whether to allow virtual files (such as Google docs or sheets) to be picked. False by default. presentationStyle?\tPresentationStyle\tiOS only - Controls how the picker is presented, e.g. on an iPad you may want to present it fullscreen. Defaults to pageSheet. transitionStyle?\tTransitionStyle\tiOS 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. ","version":null,"tagName":"h3"},{"title":"Import result","type":1,"pageTitle":"Import mode","url":"/docs/sponsor-only/picker/import-mode#import-result","content":" 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\tType\tDescriptionuri\tstring\tThe URI of the picked file. Note that it is encoded, so you might need to decode it for further processing. name\tstring | null\tThe name of the picked file, including the extension. It's very unlikely that it'd be null but in theory, it can happen. size\tnumber | null\tThe size of the picked file in bytes. type\tstring | null\tThe MIME type of the picked file. hasRequestedType\tboolean\tAndroid: 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\tstring | null\tError in case the file metadata could not be obtained. isVirtual\tboolean | null\tAndroid: 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\tstring[] | null\tAndroid: 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\tstring | null\tThe "native" type of the picked file: on Android, this is the MIME type. On iOS, it is the UTType identifier. ","version":null,"tagName":"h3"},{"title":"Keeping a local copy of the picked files","type":0,"sectionRef":"#","url":"/docs/sponsor-only/picker/keeping-local-copy","content":"Keeping a local copy of the picked files keepLocalCopy makes the file available in the app's storage. The behavior is different on iOS and Android: AndroidiOS This method opens an InputStream pointing to the picked content:// uri (from both Open and Import modes) and stores its bytes into a file - i.e. it can be used to "convert" a content:// Uri into a local file. This file's location is determined by the destination parameter. It also "converts" virtual files (such as Google Docs or sheets) into local files. note For each call of keepLocalCopy, a new unique directory is created in the app's storage, and the files are placed into it. This way, the files are isolated and subsequent calls to keepLocalCopy with the same file names do not overwrite the previous files. When writing to the filesystem, path traversal vulnerability is prevented. Writing files outside the intended destination will error. Example: keeping a local copy of the picked file import { pick, keepLocalCopy } from '@react-native-documents/picker' return ( <Button title="single file import, and ensure it is available in the local storage" onPress={async () => { try { const [{ name, uri }] = await pick() const [copyResult] = await keepLocalCopy({ files: [ { uri, fileName: name ?? 'fallback-name', }, ], destination: 'documentDirectory', }) if (copyResult.status === 'success') { // do something } } catch (err) { // see error handling } }} /> ) ","keywords":"","version":null},{"title":"Limiting selectable file types","type":0,"sectionRef":"#","url":"/docs/sponsor-only/picker/limiting-selectable-files","content":"","keywords":"","version":null},{"title":"isKnownType","type":1,"pageTitle":"Limiting selectable file types","url":"/docs/sponsor-only/picker/limiting-selectable-files#isknowntype","content":" isKnownType is a handy utility function that given one of: UTType identifier stringMIME type stringFile extension string returns the corresponding MIME type, file extension, and UTType identifier. import { isKnownType } from '@react-native-documents/picker' const { isKnown, mimeType, preferredFilenameExtension } = isKnownType({ kind: 'extension', value: 'pdf', }) If you know the file extension (or the MIME, or the UTType), then use isKnownType to find the corresponding MIME type for Android or UTType for iOS. Then pass the result to the type parameter of pick. note Prefer using the iOS implementation of isKnownType. On Android, the function does not provide UTType identifier information (as it's an iOS-only concept) and the results may not be as accurate. Different devices, based on the installed apps, may recognize different file types. ","version":null,"tagName":"h3"},{"title":"Predefined File Types","type":1,"pageTitle":"Limiting selectable file types","url":"/docs/sponsor-only/picker/limiting-selectable-files#predefined-file-types","content":" These are the most common file types, and are available in the types export. See the usage example above. import { types } from '@react-native-documents/picker' types.allFiles: All document types, on Android this is */*, on iOS it's public.itemtypes.images: All image typestypes.plainText: Plain text filestypes.audio: All audio typestypes.video: All video typestypes.pdftypes.ziptypes.csvtypes.jsontypes.doctypes.docxtypes.ppttypes.pptxtypes.xlstypes.xlsx ","version":null,"tagName":"h3"},{"title":"'Save As' dialog","type":0,"sectionRef":"#","url":"/docs/sponsor-only/picker/save-as-dialog","content":"","keywords":"","version":null},{"title":"How it works","type":1,"pageTitle":"'Save As' dialog","url":"/docs/sponsor-only/picker/save-as-dialog#how-it-works","content":" AndroidiOS Uses Intent.ACTION_CREATE_DOCUMENT internally. This is a two-step process: first, the user provides the target (location and name), then the package copies the source to the selected target. Example: opening a 'Save As' dialog import { saveDocuments } from '@react-native-documents/picker' return ( <Button title="Save some text file to a user-defined location" onPress={async () => { const [{ uri: targetUri }] = await saveDocuments({ sourceUris: ['some file uri'], copy: false, mimeType: 'text/plain', title: 'some file name', }) }} /> ) ","version":null,"tagName":"h3"},{"title":"Open mode","type":0,"sectionRef":"#","url":"/docs/sponsor-only/picker/open-mode","content":"","keywords":"","version":null},{"title":"How it works","type":1,"pageTitle":"Open mode","url":"/docs/sponsor-only/picker/open-mode#how-it-works","content":" AndroidiOS Open mode uses Intent.ACTION_OPEN_DOCUMENT internally. ","version":null,"tagName":"h3"},{"title":"Open Options","type":1,"pageTitle":"Open mode","url":"/docs/sponsor-only/picker/open-mode#open-options","content":" Name\tType\tDescriptionmode\t'open'\tspecify that you want the picker to function in the "open" mode. type?\tstring | PredefinedFileTypes | (PredefinedFileTypes | string)[]\tspecify file type(s) that you want to pick. Use types for some predefined values. requestLongTermAccess?\tboolean\tWhether to ask for long-term access permissions. False by default. allowMultiSelection?\tboolean\tWhether to allow multiple files to be picked. False by default. allowVirtualFiles?\tboolean\tAndroid only - Whether to allow virtual files (such as Google docs or sheets) to be picked. False by default. presentationStyle?\tPresentationStyle\tiOS only - Controls how the picker is presented, e.g. on an iPad you may want to present it fullscreen. Defaults to pageSheet. transitionStyle?\tTransitionStyle\t ","version":null,"tagName":"h3"},{"title":"Open result","type":1,"pageTitle":"Open mode","url":"/docs/sponsor-only/picker/open-mode#open-result","content":" 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\tType\tDescriptionuri\tstring\tThe URI of the picked file. Note that it is encoded, so you might need to decode it for further processing. name\tstring | null\tThe name of the picked file, including the extension. It's very unlikely that it'd be null but in theory, it can happen. size\tnumber | null\tThe size of the picked file in bytes. type\tstring | null\tThe MIME type of the picked file. hasRequestedType\tboolean\tAndroid: 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\tstring | null\tError in case the file metadata could not be obtained. isVirtual\tboolean | null\tAndroid: 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\tstring[] | null\tAndroid: 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\tstring | null\tThe "native" type of the picked file: on Android, this is the MIME type. On iOS, it is the UTType identifier. ","version":null,"tagName":"h3"},{"title":"Long-term file access","type":1,"pageTitle":"Open mode","url":"/docs/sponsor-only/picker/open-mode#long-term-file-access","content":" 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 } }} /> ) ","version":null,"tagName":"h2"},{"title":"Releasing Long Term Access","type":1,"pageTitle":"Open mode","url":"/docs/sponsor-only/picker/open-mode#releasing-long-term-access","content":" 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. ","version":null,"tagName":"h3"},{"title":"Releasing (stopping) Secure Access","type":1,"pageTitle":"Open mode","url":"/docs/sponsor-only/picker/open-mode#releasing-stopping-secure-access","content":" 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. ","version":null,"tagName":"h3"},{"title":"Virtual files","type":0,"sectionRef":"#","url":"/docs/sponsor-only/picker/virtual-files","content":"","keywords":"","version":null},{"title":"Obtaining a regular file from a virtual file","type":1,"pageTitle":"Virtual files","url":"/docs/sponsor-only/picker/virtual-files#obtaining-a-regular-file-from-a-virtual-file","content":" If you want to export a virtual file into a local one, use the keepLocalCopy function and double-check that the fileName parameter includes the extension.pass a mimeType value to the convertVirtualFileToType parameter. Picking a virtual file and exporting it to a local one <Button title="import virtual file (such as a document from GDrive)" onPress={async () => { const [file] = await pick({ allowVirtualFiles: true, }) const { name, uri: pickedUri, convertibleToMimeTypes } = file const virtualFileMeta = convertibleToMimeTypes && convertibleToMimeTypes[0] invariant(name && virtualFileMeta, 'name and virtualFileMeta is required') const [copyResult] = await keepLocalCopy({ files: [ { uri: pickedUri, fileName: `${name}.${virtualFileMeta.extension ?? ''}`, convertVirtualFileToType: virtualFileMeta.mimeType, }, ], destination: 'cachesDirectory', }) if (copyResult.status === 'success') { const localCopy = copyResult.localUri // do something with the local copy } }} /> For viewing or editing of virtual files you'll need to rely on the app that provided the virtual file (for example, Google Docs app for Google Docs files). The Document Viewer module can help you with that. Learn more about virtual files in this video. ","version":null,"tagName":"h2"},{"title":"Roadmap","type":0,"sectionRef":"#","url":"/docs/sponsor-only/roadmap-and-changelog","content":"","keywords":"","version":null},{"title":"Changelog","type":1,"pageTitle":"Roadmap","url":"/docs/sponsor-only/roadmap-and-changelog#changelog","content":" ","version":null,"tagName":"h2"},{"title":"@react-native-documents/picker","type":1,"pageTitle":"Roadmap","url":"/docs/sponsor-only/roadmap-and-changelog#react-native-documentspicker","content":" 10.3.0 Added saveDocuments method which implements a "save as" dialog 10.2.0 Added isKnownType method for Androidbridgeless mode support, tested with RN 0.74-rc.8 10.0.0 Initial release. Starting with version 10.0.0 to continue the series from the react-native-document-picker library. ","version":null,"tagName":"h3"},{"title":"@react-native-documents/viewer","type":1,"pageTitle":"Roadmap","url":"/docs/sponsor-only/roadmap-and-changelog#react-native-documentsviewer","content":" 1.2.0 bridgeless mode support, tested with RN 0.74-rc.8minor internal improvements 1.0.0 Initial release ","version":null,"tagName":"h3"},{"title":"Document Viewer","type":0,"sectionRef":"#","url":"/docs/sponsor-only/viewer","content":"","keywords":"","version":null},{"title":"How it works","type":1,"pageTitle":"Document Viewer","url":"/docs/sponsor-only/viewer#how-it-works","content":" AndroidiOS viewDocument uses Intent.ACTION_VIEW internally. ","version":null,"tagName":"h3"},{"title":"View a document given a uri","type":1,"pageTitle":"Document Viewer","url":"/docs/sponsor-only/viewer#view-a-document-given-a-uri","content":" Uri would come from the open or import modes of the document picker. See more in the API reference Previewing a document given a uri import { viewDocument } from '@react-native-documents/viewer' return ( <Button title="view the last imported file" onPress={() => { const uriToOpen = 'file:///path/to/your/file' viewDocument({ uri: uriToOpen }).catch(handleError) }} /> ) ","version":null,"tagName":"h3"},{"title":"View a document given a bookmark","type":1,"pageTitle":"Document Viewer","url":"/docs/sponsor-only/viewer#view-a-document-given-a-bookmark","content":" bookmark would come from the open mode, with the requestLongTermAccess option set to true. See more in the API reference Previewing a document given a bookmark import { viewDocument } from '@react-native-documents/viewer' return ( <Button title="view the last imported file" onPress={() => { const bookmark = '...' viewDocument({ bookmark }).catch(handleError) }} /> ) ","version":null,"tagName":"h3"}],"options":{"disableVersioning":true,"excludeRoutes":["/docs/license","/docs/sponsor-only/license","docs/public/document-picker"],"id":"default"}}