### Install Document Picker

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/install.mdx

Install the document picker package using yarn.

```bash
yarn add @react-native-documents/picker
```

--------------------------------

### Bare React Native Setup

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/install.mdx

After installing the package for a bare React Native project, run pod install in the ios directory and then rebuild your project with Xcode.

```bash
# Install the package first
cd ios
pod install
# Then rebuild your project with Xcode
```

--------------------------------

### Start Local Development Server

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/README.md

Starts a local development server for live preview. Changes are reflected without server restart.

```bash
yarn start
```

--------------------------------

### Install Document Viewer

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/install.mdx

Install the document viewer package using yarn.

```bash
yarn add @react-native-documents/viewer
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/README.md

Run this command to install project dependencies using Yarn.

```bash
yarn
```

--------------------------------

### Bare React Native iOS Installation

Source: https://context7.com/react-native-documents/document-picker/llms.txt

For bare React Native projects on iOS, navigate to the `ios` directory and run `pod install`.

```bash
cd ios && pod install
```

--------------------------------

### Configure Jest Setup Files

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/jest-mocks.md

Add these paths to your Jest configuration's `setupFiles` array to enable the provided mocks for document picker and viewer modules. These mocks simulate successful calls by default.

```json
{
  "setupFiles": [
    "./node_modules/@react-native-documents/picker/jest/build/jest/setup.js",
    "./node_modules/@react-native-documents/viewer/jest/build/jest/setup.js"
  ]
}
```

--------------------------------

### Expo Installation

Source: https://context7.com/react-native-documents/document-picker/llms.txt

For Expo projects, a development build is required. Run `expo prebuild --clean` followed by `expo run:ios` or `expo run:android`.

```bash
expo prebuild --clean
expo run:ios      # or expo run:android
```

--------------------------------

### V2 DocumentPicker Usage

Source: https://github.com/react-native-documents/document-picker/wiki/V2-to-V3-migration

Example of how to use DocumentPicker in V2 with a callback.

```javascript
DocumentPicker.show({
  filetype: [DocumentPickerUtil.images()],
}, (error,res) => {
  console.log(
    res.uri,
    res.type, // mime type
    res.fileName,
    res.fileSize
  );
});
```

--------------------------------

### Expo Development Build Setup

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/install.mdx

Steps to set up a development build for Expo apps when using custom native code. This is required for packages like @react-native-documents/picker and @react-native-documents/viewer as they include native modules.

```bash
# install the package first

# Build the app locally
expo prebuild --clean
expo run:ios
expo run:android
```

--------------------------------

### V3 DocumentPicker Pick with Async/Await

Source: https://github.com/react-native-documents/document-picker/wiki/V2-to-V3-migration

Example of using DocumentPicker.pick with async/await in V3. Includes error handling for cancellations.

```javascript
try {
  const res = await DocumentPicker.pick({
    type: [DocumentPicker.types.images],
  });
  console.log(
     res.uri,
     res.type, // mime type
     res.name,
     res.size
  );
} catch ( err ) {
  if ( DocumentPicker.isCancel(err) ) {
    // User cancelled the picker, exit any dialogs or menus and move on
  } else {
    throw err;
  }
}
```

--------------------------------

### Pick a directory with pickDirectory

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Opens a folder/directory picker. Use `requestLongTermAccess: true` to get persistent read/write access across app restarts. Returns a `DirectoryPickerResponse`.

```tsx
import { pickDirectory, releaseLongTermAccess, releaseSecureAccess } from '@react-native-documents/picker'
import { Platform } from 'react-native'

// One-time directory access
const handlePickDir = async () => {
  const { uri } = await pickDirectory({ requestLongTermAccess: false })
  console.log('Selected directory URI:', uri)
}

// Persistent directory access (survives app restart)
const handlePickDirLongTerm = async () => {
  const result = await pickDirectory({ requestLongTermAccess: true })
  if (result.bookmarkStatus === 'success') {
    // Persist bookmark to storage
    await AsyncStorage.setItem('dirBookmark', result.bookmark)
    console.log('Directory URI:', result.uri)
  }
  // Release when done
  if (Platform.OS === 'android') {
    await releaseLongTermAccess([result.uri])
  } else {
    await releaseSecureAccess([result.uri])
  }
}
```

--------------------------------

### Open Single File (Open Mode)

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Use `mode: 'open'` to get a reference to the original file instead of a copy. This reference is valid until the app is terminated.

```tsx
// Open mode — single file, returns a reference to the original
const handleOpenFile = async () => {
  const [file] = await pick({ mode: 'open', type: [types.pdf, types.docx] })
  console.log(file.uri) // Direct reference to original; valid until app is terminated
```

--------------------------------

### V3 DocumentPicker Pick with Promises

Source: https://github.com/react-native-documents/document-picker/wiki/V2-to-V3-migration

Example of using DocumentPicker.pick with Promises in V3. Includes error handling for cancellations.

```javascript
DocumentPicker.pick({type: [DocumentPicker.types.images]})
  .then((res) => {
    console.log(
       res.uri,
       res.type, // mime type
       res.name,
       res.size
    );
  })
  .catch((err) => {
    if ( DocumentPicker.isCancel(err) ) {
      // User cancelled the picker, exit any dialogs or menus and move on
    } else {
      throw err;
    }
  });
```

--------------------------------

### Replace pickSingle with pick

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/migration.md

Substitute the 'pickSingle' method with 'pick'. The 'pick' method returns an array of files, so destructure the first element to get the single result.

```typescript
const result = await pickSingle(options)
```

```typescript
const [result] = await pick(options)
```

--------------------------------

### Determine File Type Information

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/picker/limiting-selectable-files.md

Use `isKnownType` to get MIME type and file extension information from a given value (UTType, MIME type, or extension). This helps in constructing the `type` parameter for `pick()`.

```ts
import { isKnownType } from '@react-native-documents/picker'

const { isKnown, mimeType, preferredFilenameExtension } = isKnownType({
  kind: 'extension',
  value: 'pdf',
})

```

--------------------------------

### Picking a File in Open Mode

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/picker/open-mode.mdx

Demonstrates how to initiate the document picker in 'open' mode to select a single file. Includes basic error handling.

```tsx
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
      }
    }}
  />
)
```

--------------------------------

### Using Predefined File Types

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Demonstrates how to filter files by type using predefined constants like `types.pdf` and `types.docx`. Ensure you import `pick` and `types` from the library.

```typescript
import {
  pick,
  types,
} from '@react-native-documents/picker'
// ...
const result = await pick({
  type: [types.pdf, types.docx],
})
```

--------------------------------

### Deploy Website using SSH

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/README.md

Deploys the website using SSH. Assumes SSH keys are configured.

```bash
USE_SSH=true yarn deploy
```

--------------------------------

### Build Static Website

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/README.md

Generates static content for the website into the 'build' directory.

```bash
yarn build
```

--------------------------------

### View Document by URI or Bookmark

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Opens a native in-app document preview. Accepts either a URI or a bookmark. On iOS, it uses QuickLook; on Android, it uses Intent.ACTION_VIEW. The promise resolves immediately after the OS receives the request.

```tsx
import { viewDocument, isErrorWithCode, errorCodes } from '@react-native-documents/viewer'

// View by URI (from pick import/open mode or keepLocalCopy)
const handleViewUri = async () => {
  try {
    await viewDocument({
      uri: 'file:///path/to/file.pdf',
      mimeType: 'application/pdf',        // Recommended on Android
      headerTitle: 'My Document',         // iOS only: title in the viewer header
      presentationStyle: 'pageSheet',     // iOS only: fullScreen | pageSheet | formSheet | overFullScreen
      grantPermissions: 'read',           // Android only: 'read' | 'write'
    })
  } catch (err) {
    if (isErrorWithCode(err) && err.code === errorCodes.UNABLE_TO_OPEN_FILE_TYPE) {
      console.warn('No app available to open this file type')
    }
  }
}

// View using a stored bookmark (works after app restart)
const handleViewBookmark = async () => {
  const bookmark = await AsyncStorage.getItem('myBookmark')
  if (bookmark) {
    await viewDocument({ bookmark }).catch(console.error)
  }
}
```

--------------------------------

### pick()

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

The primary method for picking files, supporting both 'import' and 'open' modes with various options.

```APIDOC
## pick()

### Description
Initiates the document picking process for importing or opening files.

### Method
`pick`

### Parameters
#### Path Parameters
- **options** (O) - Optional - Configuration options for the picker, such as mode, file types, and transition style.

### Returns
`PickResponse<O>`
```

--------------------------------

### viewDocument(options)

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Opens a native in-app document preview. Resolves with null after the OS receives the request. Accepts either a `uri` or a `bookmark`.

```APIDOC
## `viewDocument(options)` — Preview a document

Opens a native in-app document preview. On iOS, uses QuickLook. On Android, uses `Intent.ACTION_VIEW`. The promise resolves with `null` immediately after the OS receives the request ("fire and forget"). Accepts either a `uri` or a `bookmark` (obtained from `pick` with `requestLongTermAccess: true`).

### Parameters

- **uri** (string) - Required - The URI of the document to preview.
- **bookmark** (string) - Required - A bookmark obtained from `pick` with `requestLongTermAccess: true`.
- **mimeType** (string) - Optional - Recommended on Android. The MIME type of the document.
- **headerTitle** (string) - Optional - iOS only: The title to display in the viewer header.
- **presentationStyle** (string) - Optional - iOS only: The presentation style for the viewer (`fullScreen`, `pageSheet`, `formSheet`, `overFullScreen`).
- **grantPermissions** (string) - Optional - Android only: Permissions to grant (`read` or `write`).

### Request Example

```tsx
import { viewDocument } from '@react-native-documents/viewer'

// View by URI
await viewDocument({
  uri: 'file:///path/to/file.pdf',
  mimeType: 'application/pdf',
  headerTitle: 'My Document',
  presentationStyle: 'pageSheet',
  grantPermissions: 'read',
})

// View using a stored bookmark
const bookmark = await AsyncStorage.getItem('myBookmark')
if (bookmark) {
  await viewDocument({ bookmark })
}
```

### Response

- **null** - The promise resolves with `null` after the OS receives the request.
```

--------------------------------

### Android Namespace Replacement in MainApplication.java

Source: https://github.com/react-native-documents/document-picker/wiki/V2-to-V3-migration

Shows the necessary replacements for the Android namespace and package import in `MainApplication.java`.

```java
import io.github.elyx0.reactnativedocumentpicker.DocumentPickerPackage; // Import package
```

```java
new DocumentPickerPackage() // Add package
```

--------------------------------

### pickDirectory

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Opens a folder/directory picker, optionally requesting persistent access across app restarts.

```APIDOC
## `pickDirectory(options?)` — Pick a directory

Opens a folder/directory picker. Use `requestLongTermAccess: true` to get persistent read/write access to the chosen directory across app restarts. Returns a `DirectoryPickerResponse` (with optional `BookmarkingResponse` when long-term access is requested).

### Parameters

- **requestLongTermAccess** (boolean) - Optional - If true, requests persistent access to the directory.

### Response

- **DirectoryPickerResponse**
  - **uri** (string) - The URI of the selected directory.
  - **bookmarkStatus** ('success' | 'error' | 'notAvailable') - On Android, indicates the status of bookmarking for long-term access.
  - **bookmark** (string) - The bookmark data for long-term access (Android only).

### Request Example

```javascript
// One-time access
const { uri } = await pickDirectory({ requestLongTermAccess: false })

// Persistent access
const result = await pickDirectory({ requestLongTermAccess: true })
if (result.bookmarkStatus === 'success') {
  // Persist bookmark to storage
  await AsyncStorage.setItem('dirBookmark', result.bookmark)
}
```
```

--------------------------------

### Pick Single PDF (Import Mode)

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Use the `pick` function to select a single PDF file. The default mode is 'import', providing a temporary copy. Error handling for cancellation is included.

```tsx
import { pick, keepLocalCopy, types, isErrorWithCode, errorCodes } from '@react-native-documents/picker'

// Import mode — single PDF
const handlePickSinglePdf = async () => {
  try {
    const [file] = await pick({ type: types.pdf })
    console.log(file.uri)    // content:// (Android) or file:// (iOS)
    console.log(file.name)   // "report.pdf"
    console.log(file.size)   // 204800
    console.log(file.type)   // "application/pdf"
    console.log(file.hasRequestedType) // true if the file matches the requested type
  } catch (err) {
    if (isErrorWithCode(err) && err.code === errorCodes.OPERATION_CANCELED) return
    console.error(err)
  }
}
```

--------------------------------

### Pick Multiple Files (Import Mode)

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Allow users to select multiple files of any type by setting `allowMultiSelection: true` in the `pick` options.

```tsx
// Import mode — multiple files, any type
const handlePickMultiple = async () => {
  const files = await pick({ allowMultiSelection: true })
  // files is NonEmptyArray<DocumentPickerResponse>
  files.forEach(f => console.log(f.name, f.uri))
```

--------------------------------

### Import Options

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/picker/import-mode.mdx

Configuration options for the document picker when in import mode.

```APIDOC
## Import Options

This section details the available options for configuring the document picker when importing files.

### Options

- **`type`** (`string` | `PredefinedFileTypes` | (`PredefinedFileTypes` | `string`)[]): Optional. Specifies the file type(s) to pick. Can be a single type, an array of types, or use predefined values.
- **`allowMultiSelection`** (`boolean`): Optional. If true, allows multiple files to be picked. Defaults to false.
- **`allowVirtualFiles`** (`boolean`): Optional. Android only. If true, allows virtual files (e.g., Google Docs) to be picked. Defaults to false.
- **`presentationStyle`** (`PresentationStyle`): Optional. iOS only. Controls how the picker is presented (e.g., `pageSheet`, `fullScreen`). Defaults to `pageSheet`.
- **`transitionStyle`** (`TransitionStyle`): Optional. iOS only. Configures the transition style of the picker. Defaults to `coverVertical`.
```

--------------------------------

### Pick a file in import mode

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/picker/import-mode.mdx

Use this snippet to pick a single file using the default import mode. The `pick()` function returns an array of picked documents. You can explicitly set `mode: 'import'` but it is not necessary as it's the default.

```tsx
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
      }
    }}
  />
)
```

--------------------------------

### pick()

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Opens the document picker interface to allow users to select documents. It supports various options for selection mode and file types.

```APIDOC
## pick()

### Description
Opens the document picker interface to allow users to select documents. It supports various options for selection mode and file types.

### Type Parameters
- `O` *extends* `DocumentPickerOptions`

### Parameters
- `options?` (`O`): Optional configuration for the document picker.

### Returns
`PickResponse`

### DocumentPickerOptionsBase
Base options object for the document picker.

#### Properties
- `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. Defaults to `pageSheet`.
- `transitionStyle?` (`TransitionStyle`): iOS only - Configures the transition style of the picker. Defaults to `coverVertical`.
- `type?` (`string` | `PredefinedFileTypes` | (`PredefinedFileTypes` | `string`)[]): Specify file type(s) that you want to pick. Use `types` for some predefined values.

### DocumentPickerOptionsImport
Present the document picker in import mode.

#### Type Declaration
- `mode?`: "import"
- `requestLongTermAccess?`: `never`

### DocumentPickerOptionsOpenLongTerm
Present the document picker in open mode, with long-term permissions to access the opened file.

#### Type Declaration
- `mode`: "open"
- `requestLongTermAccess`: `true`

### DocumentPickerOptionsOpenOnce
Present the document picker in open mode, with permissions to access the file for a limited time (until the app terminates).

#### Type Declaration
- `mode`: "open"
- `requestLongTermAccess?`: `false`

### DocumentPickerResponse
#### Properties
- `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`
```

--------------------------------

### Preview Document by URI

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/viewer.mdx

Use this snippet to preview a document when you have its URI. Ensure the `mimeType` is correctly specified. The promise rejects if an error occurs during the preview request.

```tsx
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, mimeType: 'some-mime' }).catch(handleError)
    }}
  />
)
```

--------------------------------

### pick(options?) — Pick one or more files

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Opens the native document picker to allow users to select one or more files. Supports different modes like 'import' (default) and 'open', and can request long-term access for persistent file references.

```APIDOC
## pick(options?)

### Description
Opens the native document picker to allow users to select one or more files. The default mode is 'import' which provides a temporary copy of the selected file. Pass `mode: 'open'` to get a reference to the original file. Always returns a `NonEmptyArray<DocumentPickerResponse>`, so destructuring the first element is guaranteed safe even with `noUncheckedIndexedAccess`.

### Method
`pick`

### Parameters
#### options
- **type** (string | string[]) - Optional - Specifies the allowed file types (e.g., `types.pdf`, `[types.pdf, types.docx]`).
- **allowMultiSelection** (boolean) - Optional - If true, allows the user to select multiple files. Defaults to false.
- **mode** (string) - Optional - The picking mode. Can be `'import'` (default) or `'open'`.
- **requestLongTermAccess** (boolean) - Optional - If true, requests long-term access to the picked file, allowing it to persist across app restarts. Requires `mode: 'open'`.

### Request Example
```javascript
// Import mode — single PDF
const [file] = await pick({ type: types.pdf })

// Import mode — multiple files, any type
const files = await pick({ allowMultiSelection: true })

// Open mode — single file, returns a reference to the original
const [file] = await pick({ mode: 'open', type: [types.pdf, types.docx] })

// Open mode — with long-term access
const [file] = await pick({
  mode: 'open',
  requestLongTermAccess: true,
  type: types.pdf,
})
```

### Response
#### Success Response
Returns a `NonEmptyArray<DocumentPickerResponse>` containing information about the selected files.
Each `DocumentPickerResponse` object may include:
- **uri** (string): The URI of the selected file (e.g., `content://` on Android, `file://` on iOS).
- **name** (string): The name of the file.
- **size** (number): The size of the file in bytes.
- **type** (string): The MIME type of the file.
- **hasRequestedType** (boolean): True if the file matches the requested type.
- **bookmarkStatus** (string): Only present if `requestLongTermAccess` was true. Indicates the status of the bookmark request ('success' or 'failure').
- **bookmark** (string): Only present if `requestLongTermAccess` was true and `bookmarkStatus` is 'success'. A bookmark string that can be used with `viewDocument`.

#### Error Handling
- Throws an error if the operation is canceled or an issue occurs.
- Use `isErrorWithCode` and `errorCodes` to handle specific errors like `OPERATION_CANCELED`.
```

--------------------------------

### Selecting a Directory

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/picker/directory-picker.mdx

Use this snippet to allow users to select a directory. Set `requestLongTermAccess` to `true` for persistent access across app restarts. Handle potential errors during the picking process.

```tsx
import { pickDirectory } from '@react-native-documents/picker'

return (
  <Button
    title="open directory"
    onPress={async () => {
      try {
        const { uri } = await pickDirectory({
          requestLongTermAccess: false,
        })
        // do something with the uri
      } catch (err) {
        // see error handling section
        console.error(err)
      }
    }}
  />
)
```

--------------------------------

### Import Result

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/picker/import-mode.mdx

Describes the structure and content of the result returned after picking files.

```APIDOC
## Import Result

The result of the `pick` function is an array of picked files. The structure of this array depends on the `allowMultiSelection` option.

- If `allowMultiSelection` is `false` (the default), the array will contain a single file object.
- If `allowMultiSelection` is `true`, the array can contain one or more file objects.
```

--------------------------------

### Deploy Website without SSH

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/README.md

Deploys the website without SSH. Requires specifying the GitHub username.

```bash
GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Pick and Export Virtual File to Local Copy

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/picker/virtual-files.md

Use `allowVirtualFiles: true` to pick virtual files. The `keepLocalCopy` function can then be used to export these virtual files to a local copy, specifying the desired `fileName` with extension and `mimeType` for conversion.

```tsx
import { Button } from 'react-native';
import { pick, keepLocalCopy } from 'react-native-document-picker';
import invariant from 'invariant';

// ... inside a component
<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
    }
  }}
/>
```

--------------------------------

### saveDocuments

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Presents the OS 'Save As' dialog, allowing the user to choose a location and name for saving files.

```APIDOC
## `saveDocuments(options)` — "Save As" dialog

Presents the OS "Save As" dialog, allowing the user to choose where to save a file. On Android, only one file can be saved at a time; iOS supports saving multiple files at once.

### Parameters

- **sourceUris** (Array<string>) - Required - An array of URIs pointing to the files to be saved.
- **mimeType** (string) - Optional (Android only) - Helps the OS find compatible apps for saving.
- **fileName** (string) - Optional (Android only) - Pre-fills the filename field in the dialog.
- **copy** (boolean) - Optional (iOS only, default: false) - If true, copies the file; if false, moves the file.

### Request Example

```javascript
await saveDocuments({
  sourceUris: ['file:///path/to/your/file.pdf'],
  mimeType: 'application/pdf',
  fileName: 'MyExport.pdf',
  copy: false,
})
```

### Response

- **Array<SavedDocumentResult>** - An array of results, one for each file attempted to save.
  - **uri** (string) - The URI of the saved file.
  - **name** (string) - The name of the saved file.
  - **error** (string) - An error message if the save operation failed.
```

--------------------------------

### Preview Document by Bookmark

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/viewer.mdx

Use this snippet to preview a document when you have a bookmark, typically obtained with `requestLongTermAccess`. The promise rejects if an error occurs during the preview request.

```tsx
import { viewDocument } from '@react-native-documents/viewer'

return (
  <Button
    title="view the last imported file"
    onPress={() => {
      const bookmark = '...'
      viewDocument({ bookmark }).catch(handleError)
    }}
  />
)
```

--------------------------------

### DirectoryPickerOptionsBase Type

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Base options for directory picking, primarily influencing iOS presentation and transition styles.

```APIDOC
### DirectoryPickerOptionsBase

> **DirectoryPickerOptionsBase** = { `presentationStyle?`: [`PresentationStyle`](#presentationstyle-2); `transitionStyle?`: [`TransitionStyle`](#transitionstyle-2); }

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](#directorypickeroptions)
which extend this type

#### Properties

##### presentationStyle?
> `optional` **presentationStyle**: [`PresentationStyle`](#presentationstyle-2)

iOS only - Controls how the picker is presented, e.g. on an iPad you may want to present it fullscreen. Defaults to `pageSheet`.

##### transitionStyle?
> `optional` **transitionStyle**: [`TransitionStyle`](#transitionstyle-2)

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

--------------------------------

### types

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Provides platform-aware constants for predefined file types, which can be used with the `type` option of the `pick` function.

```APIDOC
## `types` — Predefined file type constants

Platform-aware constants that resolve to MIME types on Android and UTType identifiers on iOS. Use them with the `type` option of `pick`.

### Available Keys

`allFiles`, `audio`, `csv`, `doc`, `docx`, `images`, `pdf`, `plainText`, `json`, `ppt`, `pptx`, `video`, `xls`, `xlsx`, `zip`

### Request Example

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

// Pick only spreadsheet files
const [file] = await pick({ type: [types.xls, types.xlsx] })

// Pick any image
const [image] = await pick({ type: types.images })

// Pick any file
const [any] = await pick({ type: types.allFiles })

// Mix predefined + custom MIME type
const [doc] = await pick({ type: [types.pdf, 'application/rtf'] })
```
```

--------------------------------

### Import Predefined File Types

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/picker/limiting-selectable-files.md

Import the `types` object from the picker module to access commonly used file type constants.

```ts
import { types } from '@react-native-documents/picker'

```

--------------------------------

### BookmarkingResponse

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Represents the response when requesting long-term access to a directory or file. It includes a bookmark string for future access or an error message if access fails.

```APIDOC
## Type Alias: BookmarkingResponse

> **BookmarkingResponse** = { `bookmark`: `string`; `bookmarkStatus`: "success"; } | { `bookmarkError`: `string`; `bookmarkStatus`: "error"; }

This object is returned when you've requested long-term access to a directory or file. Store the `bookmark` opaque string to access the same directory or file in the future by passing it to the document viewer.
```

--------------------------------

### isKnownType(options)

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Synchronously queries the OS type system to inspect a file type. Returns an object indicating if the type is known and its preferred extension or MIME type.

```APIDOC
## `isKnownType(options)` — Inspect a file type

Synchronously queries the OS type system. On iOS, checks if the UTType is known; on Android, queries the MIME type database. Useful for validating custom MIME types or extensions before passing them to `pick`.

### Parameters

- **kind** (string) - Required - The type of identifier to check (`mimeType`, `extension`, or `UTType`).
- **value** (string) - Required - The value of the identifier to check.

### Response

An object with the following properties:

- **isKnown** (boolean) - Whether the file type is known by the OS.
- **preferredFilenameExtension** (string | null) - The preferred file extension for this type.
- **UTType** (string | null) - The UTType identifier (iOS only).
- **mimeType** (string | null) - The MIME type.

### Request Example

```tsx
import { isKnownType } from '@react-native-documents/picker'

// Check by MIME type
const pdf = isKnownType({ kind: 'mimeType', value: 'application/pdf' })
console.log(pdf.isKnown)                    // true
console.log(pdf.preferredFilenameExtension) // "pdf"
console.log(pdf.UTType)                     // "com.adobe.pdf" (iOS) / null (Android)

// Check by file extension
const docx = isKnownType({ kind: 'extension', value: 'docx' })
console.log(docx.mimeType) // "application/vnd.openxmlformats-officedocument.wordprocessingml.document"

// Check by UTType identifier (iOS-centric)
const folder = isKnownType({ kind: 'UTType', value: 'public.folder' })
console.log(folder.isKnown) // true on iOS
```
```

--------------------------------

### viewDocument

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-viewer-api/index.md

Displays a document to the user. This function can accept options for viewing a document via its URI or a bookmark.

```APIDOC
## viewDocument()

### Description
Displays a document to the user. This function can accept options for viewing a document via its URI or a bookmark.

### Parameters
#### Request Body
- **data** (ViewDocumentOptions) - Required - Options for viewing a document. This can be either `OptionsViewBookmark` or `OptionsViewUri`.

### Returns
- `Promise<null>` - A promise that resolves to null when the document has been viewed.
```

--------------------------------

### saveDocuments()

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

The method for opening a "save as" dialog and saving source file(s) to a new location. Note that on Android, only one file can be saved at a time.

```APIDOC
## saveDocuments()

### Description
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
- `options` (`SaveDocumentsOptions`): Configuration options for saving documents.

### Returns
`Promise`

### SaveDocumentsOptions
Options for the `saveDocuments` method.

### SaveDocumentsResponse
Response object for the `saveDocuments` method.
```

--------------------------------

### IsKnownTypeOptions

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Specifies the options for checking if a file type is known, including the kind of type (UTType, mimeType, extension) and its value.

```APIDOC
## Type Alias: IsKnownTypeOptions

> **IsKnownTypeOptions** = { `kind`: `"UTType"` | `"mimeType"` | `"extension"`; `value`: `string`; }

#### Properties

*   **kind** (`"UTType"` | `"mimeType"` | `"extension"`): The kind of value you're passing.
*   **value** (`string`): The value you're checking, for example: `application/pdf`, `com.adobe.pdf`, `pdf`.
```

--------------------------------

### Pick Files with Predefined Types

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Uses predefined platform-aware constants for file types when picking documents. These constants resolve to MIME types on Android and UTType identifiers on iOS. Can be mixed with custom MIME types.

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

// Available keys: allFiles, audio, csv, doc, docx, images, pdf,
//                 plainText, json, ppt, pptx, video, xls, xlsx, zip

// Pick only spreadsheet files
const [file] = await pick({ type: [types.xls, types.xlsx] })

// Pick any image
const [image] = await pick({ type: types.images })

// Pick any file
const [any] = await pick({ type: types.allFiles })

// Mix predefined + custom MIME type
const [doc] = await pick({ type: [types.pdf, 'application/rtf'] })
```

--------------------------------

### Open 'Save As' dialog

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/picker/save-as-dialog.mdx

Opens a 'Save As' dialog to allow the user to choose a location and name for saving a file. Ensure the `saveDocuments` function is imported from '@react-native-documents/picker'.

```tsx
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',
        fileName: 'some file name',
      })
    }}
  />
)
```

--------------------------------

### Save documents with saveDocuments

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Presents the OS "Save As" dialog, allowing the user to choose where to save a file. On Android, only one file can be saved at a time; iOS supports saving multiple files at once. `copy: false` on iOS moves the file.

```tsx
import { saveDocuments } from '@react-native-documents/picker'

const handleSaveAs = async () => {
  // sourceUri must point to an existing file (file:// or content://)
  const results = await saveDocuments({
    sourceUris: ['file:///data/user/0/com.myapp/cache/export.pdf'],
    mimeType: 'application/pdf',   // Android: helps the OS find compatible apps
    fileName: 'MyExport.pdf',      // Android: pre-fills the filename field
    copy: false,                   // iOS: false = move, true = copy (default: false)
  })

  for (const saved of results) {
    if (saved.error) {
      console.error('Save error:', saved.error)
    } else {
      console.log('Saved to:', saved.uri, 'as', saved.name)
    }
  }
}
```

--------------------------------

### FileToCopy

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Defines the structure for a file whose copy should be kept in the app's storage, including its URI, desired filename, and optional conversion type.

```APIDOC
## Type Alias: FileToCopy

> **FileToCopy** = { `convertVirtualFileToType?`: `string`; `fileName`: `string`; `uri`: `string`; }

Object type representing the file(s) whose copy should be kept in the app's storage. This is a parameter for the `keepLocalCopy` function.

### Properties

*   **convertVirtualFileToType?** (`string`, optional): Only for Android virtual files. Specifies the type to export the file to (e.g., `application/pdf`). Use values from `convertibleToMimeTypes` from the `pick()` method response.
*   **fileName** (`string`): The name of the resulting file, including the extension. Can use the `name` field from the `pick()` method response. Example: `someFile.pdf`.
*   **uri** (`string`): The URI to keep a local copy of. This should be a `content://` (Android) or `file://` (iOS) URI that the user has previously picked.
```

--------------------------------

### PresentationStyle

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Defines the presentation style for the document picker on iOS, allowing customization of how the picker modal appears.

```APIDOC
## Type Alias: PresentationStyle

> **PresentationStyle** = `"fullScreen"` | `"pageSheet"` | `"formSheet"` | `"overFullScreen"` | `undefined`

iOS only. Configure the presentation style of the picker.
```

--------------------------------

### PredefinedFileTypes

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Represents predefined file types that can be used to filter files in the document picker, combining all MIME types and Apple UTIs.

```APIDOC
## Type Alias: PredefinedFileTypes

> **PredefinedFileTypes** = `Flatten`<`AllMimeTypes`> | `AllAppleUTIs`

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

```ts
import {
  pick,
  types,
} from '@react-native-documents/picker'
// ...
const result = await pick({
  type: [types.pdf, types.docx],
})
```
```

--------------------------------

### Open File with Long-Term Access

Source: https://context7.com/react-native-documents/document-picker/llms.txt

Request long-term access to a file by setting `requestLongTermAccess: true`. The returned bookmark can be stored and used later with `viewDocument`.

```tsx
// Open mode — with long-term access (persists across app restarts)
const handleOpenWithBookmark = async () => {
  const [file] = await pick({
    mode: 'open',
    requestLongTermAccess: true,
    type: types.pdf,
  })
  if (file.bookmarkStatus === 'success') {
    // Store file.bookmark to AsyncStorage / MMKV — use it later with viewDocument
    await AsyncStorage.setItem('myBookmark', file.bookmark)
  }
```

--------------------------------

### DirectoryPickerResponse Type

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Represents the response from the directory picker when long-term access was not requested.

```APIDOC
### DirectoryPickerResponse

> **DirectoryPickerResponse** = { `uri`: `string`; }

This object represents the response from the directory picker, when long-term access was not requested.

#### Properties

##### uri
> **uri**: `string`

The (percent-encoded) directory selected by user.
```

--------------------------------

### KeepLocalCopyOptions

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Options for the `keepLocalCopy` function, specifying the destination directory and the files to copy.

```APIDOC
## Type Alias: KeepLocalCopyOptions

> **KeepLocalCopyOptions** = { `destination`: `"cachesDirectory"` | `"documentDirectory"`; `files`: [`NonEmptyArray`](#nonemptyarray)<[`FileToCopy`](#filetocopy)>; }

Options for the `keepLocalCopy` function.

#### Properties

*   **destination** (`"cachesDirectory"` | `"documentDirectory"`): The destination directory for the copied files.
*   **files** ([`NonEmptyArray`](#nonemptyarray)<[`FileToCopy`](#filetocopy)>): An array of files to copy, each defined by the `FileToCopy` type. This array must contain at least one element.
```

--------------------------------

### VirtualFileMeta Type

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Defines the structure for metadata related to virtual files, including extension and MIME type.

```APIDOC
## VirtualFileMeta

> **VirtualFileMeta** = { `extension`: `string` | `null`; `mimeType`: `string`; }

### Properties

##### extension
> **extension**: `string` | `null`

The registered extension for the given MIME type. Note that some MIME types map to multiple extensions. This call returns the most common extension for the given MIME type. Example: `pdf`

##### mimeType
> **mimeType**: `string`

The MIME type of the file. This is necessary to export the virtual file to a local file. Example: `application/pdf`
```

--------------------------------

### Request Long-Term File Access

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/sponsor-only/picker/open-mode.mdx

Use `requestLongTermAccess: true` to enable persistent access to a file. Store the returned `bookmark` and `bookmarkStatus` to re-access the file later. Handle potential errors during the pick operation.

```tsx
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
      }
    }}
  />
)
```

--------------------------------

### LocalCopyResponse

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Indicates the success or failure of a local file copy operation, providing the local URI on success or an error message on failure.

```APIDOC
## Type Alias: LocalCopyResponse

> **LocalCopyResponse** = { `localUri`: `string`; `sourceUri`: `string`; `status`: `"success"`; } | { `copyError`: `string`; `sourceUri`: `string`; `status`: `"error"`; }

Indicates, for each URI passed to `keepLocalCopy`, whether the local copy was successful.

*   If successful: `status` is `"success"` and `localUri` contains the local URI.
*   If not successful: `status` is `"error"` and `copyError` contains the error message.
```

--------------------------------

### DocumentPickerResponse Properties

Source: https://github.com/react-native-documents/document-picker/blob/main/docs/docs/doc-picker-api/index.md

Properties available in the DocumentPickerResponse object, providing metadata about the picked file.

```APIDOC
## DocumentPickerResponse Properties

### Description
Provides metadata about the picked file.

### Properties

##### convertibleToMimeTypes
> **convertibleToMimeTypes**: [`VirtualFileMeta`](#virtualfilemeta)[] | `null`

Android: The target types the virtual file can be converted to. Useful for [keepLocalCopy](#keeplocalcopy).
This field is only present if `isVirtual` is true, and only on Android 7.0+. Always `null` on iOS.

##### error
> **error**: `string` | `null`

Error in case the file metadata could not be obtained.

##### hasRequestedType
> **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` is 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
> **isVirtual**: `boolean` | `null`

Android: whether the file is a virtual file (such as Google docs or sheets). This is `null` on pre-Android 7.0 devices. On iOS, it's always `false`.

##### name
> **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
> **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
> **size**: `number` | `null`

The size of the picked file in bytes.

##### type
> **type**: `string` | `null`

The MIME type of the picked file.

##### uri
> **uri**: `string`

The URI of the picked file. This is a percent-encoded `content://` uri (Android), or a `file://` uri (iOS).
```