DOCSEARCHbyAlgolia
Submit Docs

react-native-documents

repository·main·Indexed 23 days ago

https://github.com/react-native-documents/document-picker

A React Native library for picking, accessing, and previewing documents from local device storage and cloud providers like Google Drive and iCloud. It consists of two primary packages: @react-native-documents/picker for selecting documents and directories, and @react-native-documents/viewer for previewing documents using native system viewers like QuickLook on iOS and Intents on Android.

Tokens
23.7K
Snippets
33
Records
89
Agent score
79%

What's inside react-native-documents

  3. Overview of react-native-documents

    main

    The react-native-documents repository provides React Native modules designed for handling documents within mobile applications. It is split into two primary packages:

    1. @react-native-documents/picker: Used for selecting documents from the device.
    2. @react-native-documents/viewer: Used for viewing documents within the application.

  4. Introduction to @react-native-documents/picker and @react-native-documents/viewer

    main

    The @react-native-documents/picker and @react-native-documents/viewer packages allow React Native applications to pick, save ('save as' dialog), and view documents from the device's file system or remote locations.

    Key components:

    • @react-native-documents/picker: Provides APIs for selecting files and triggering 'save as' dialogs.
    • @react-native-documents/viewer: A companion package designed for viewing documents selected via the picker.

  6. How directory picking works on Android and iOS

    main

    The pickDirectory implementation relies on native platform APIs:

    • Android: Uses Intent.ACTION_OPEN_DOCUMENT_TREE internally to allow the user to select a directory tree.
    • iOS: Uses UIDocumentPickerViewController init(forOpeningContentTypes:asCopy:) internally.

    Note that there are security limitations regarding document tree access on Android that may affect how you interact with the selected directory.

  7. Choosing between Open and Import modes on Android

    main

    On Android, the @react-native-documents/picker library provides two distinct modes for selecting files: Open Mode and Import Mode.

    In practice, these modes are similar, and you can usually use either one depending on your requirements. If you need to ensure the file is accessible after the picker is closed, it is often recommended to use either mode in combination with the keepLocalCopy option.

    • Open Mode uses Intent.ACTION_OPEN_DOCUMENT under the hood.
    • Import Mode uses Intent.ACTION_GET_CONTENT under the hood.

  8. Handle nullable file metadata fields

    main

    When working with the document picker, many fields in the returned file metadata are nullable. This is because certain metadata might not be available depending on the platform or the source of the file.

    Specifically on Android, if a user selects a file from a Document Provider that does not expose specific information, those fields will be null. Always implement null checks or provide fallback values when accessing metadata fields to prevent runtime errors.

  9. Migrating from react-native-document-picker to @react-native-documents/picker

    main

    The original react-native-document-picker has been fully rewritten and replaced by @react-native-documents/picker.

    Notable API changes include:

    • TypeScript improvements: Uses Discriminated Unions to reduce nullable fields and prevent accessing non-existent properties.
    • Streamlined picking: The pickSingle method has been replaced by a more streamlined pick() method that returns an array (e.g., const [result] = pick()).

    For detailed instructions, refer to the migration guide.

  10. Request long-term file access

    main

    By setting requestLongTermAccess: true in the pick options, your app is granted access to the file that persists even after the app or device is restarted.

    To use this functionality:

    1. Set requestLongTermAccess: true in your pick call.
    2. Check if result.bookmarkStatus === 'success'.
    3. If successful, retrieve the result.bookmark (an opaque string).
    4. Store this bookmark string locally (e.g., in localStorage or a database).
    5. In future sessions, use the stored bookmark to resolve the file URI.

    Note: If you need to resolve the bookmark in a custom native module, refer to the Document viewer source for implementation details.

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

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,
    }
    // Store the bookmark for future use
    localStorage.set('bookmark', JSON.stringify(bookmarkToStore))
  } else {
    console.error(result)
  }
} catch (err) {
  // handle error
}

  11. Use the Document Viewer to preview files

    main

    The @react-native-documents/viewer module allows you to preview files using either a uri or a bookmark. It is designed to work seamlessly with files returned by the document picker's open and import modes, including support for virtual files and long-term access.

    Key Characteristics

    • Fire-and-forget: The viewDocument function returns a promise that resolves as soon as the package requests the OS to present the preview. A resolution of null indicates success, while a rejection indicates an error.
    • Platform Implementation:
      • Android: Uses Intent.ACTION_VIEW internally.
      • iOS: Uses the QuickLook framework internally.