nitro-picker

Open the system document picker on iOS and Android. Selected files arrive as local copies in your app's cache, ready to read or upload.

Install

bun add nitro-picker react-native-nitro-modules
cd ios && pod install

| Requirement | Version | | --- | --- | | React Native | 0.75+ | | Nitro Modules | 0.35.9 or later in the 0.35.x series | | iOS | 15.1+ and your React Native version's minimum deployment target | | Android | API 24+ |

Rebuild your native app after installing.

The picker uses the system's document access flow. You do not need storage permission.

Pick a file

import { Files } from 'nitro-picker'

try {
  const files = await Files.pickFiles({})
  if (files.length === 0) console.log('Canceled')
  else console.log(files[0].uri)
} catch (error) {
  console.error('Could not copy the selected file', error)
}

Canceling resolves with an empty array. Opening a second picker while one is already active rejects the new request.

Filter by file type

const documents = await Files.pickFiles({
  mimeTypes: ['application/pdf'],
  allowMultiple: true,
})
for (const file of documents) {
  console.log(file.name, file.byteSize, file.mimeType)
}

Use registered MIME types, */*, image/*, audio/*, video/*, or text/*. iOS rejects types it cannot resolve.

API

The package exports Files, plus the FilePicker, PickOptions, and PickedFile types.

Files.pickFiles(options)

Returns Promise<PickedFile[]>. Pass {} to select one file of any type.

| Option | Type | Default | | --- | --- | --- | | mimeTypes | string[] | All files | | allowMultiple | boolean | false |

Each result describes the copy in your cache:

| Field | Type | Meaning | | --- | --- | --- | | uri | string | Local file:// URI. | | name | string | Original filename, including its extension when the provider supplies one. | | byteSize | number | Size of the copied file in bytes. | | mimeType | Optional string | MIME type, when the provider can identify it. |

Keeping and deleting files

Your app owns the returned copies. Move files to permanent storage with your filesystem library if they must survive cache eviction. Delete copies when you finish using them.

The promise resolves after every copy completes. A file stored in the cloud may need to download first. If any copy fails, the whole operation rejects and removes the partial copies from that request.

Example and reference

The example screen covers single selection, multiple PDFs, cancellation, and errors. The TypeScript contract contains the method definition.

Native behavior follows Apple's document picker and Android's Storage Access Framework.

License

MIT. See LICENSE.