README

Capacitor (Multi-) Photopicker Plugin

The Photopicker API allows the user to select one or more photos from the system-wide media library.

The selected photos can be (down)scaled and compressed. The data is provided in the form of temporary files in the user's cache directory. The API provides the URIs of the processed photos.

In order to use the photos in a Capacitor application, they have to be moved from the cache directory to the final storage location.

Installation

npm install enertrag-photopicker

(Of course, the usual Capacitor procedure npx cap sync must be executed afterwards.)

iOS Notes

Important: this plugin requires iOS 14 or later.

iOS requires the following usage description be added and filled out for your app in Info.plist:

NSPhotoLibraryUsageDescription (Privacy - Photo Library Usage Description)

Read about Configuring Info.plist in the iOS Guide for more information on setting iOS permissions in Xcode

Selected images are persisted in the users cache (temporary) folder. As mentioned you should move it to the final destination.

Android Notes

To use this plugin you have to register it in your MainActivity.

import ...
import com.enertrag.plugins.photopicker.Photopicker;

public class MainActivity extends BridgeActivity {

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Initializes the Bridge
    this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
      // Additional plugins you've installed go here
      add(Photopicker.class);
    }});
  }
}

On your MainActivity.java file add import com.enertrag.plugins.photopicker.Photopicker; and then inside the init callback add(Photopicker.class);

This API requires the following permissions be added to your AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

The storage permissions are for reading/saving photo files.

Read about Setting Permissions in the Android Guide for more information on setting Android permissions.

Example

import { Plugins } from '@capacitor/core';
const { Photopicker } = Plugins;

...

async addPhotos() {

      const result = await Photopicker.getPhotos();
      if (result.selected) {

        for (const url of result.urls) {
            // ... do something with the url if it's not empty
            if(url) {
                // ...
            }
        }
      }
}

Alternatively, if the code completion does not work, the import can be formulated as follows:

import { EAGPhotopicker } from 'enertrag-photopicker';
const Photopicker = new EAGPhotopicker();

API

getPhotos()

getPhotos(options: PhotopickerOptions) => Promise<PhotopickerResponse>

Prompt the user to pick one or more photos from an album.

The method call may fail if the user denies the permission request.

Returns: Promise<PhotopickerResponse>

Interfaces

PhotopickerOptions

Prop	Type	Description
`maxSize`	`number`	The maximum length of one side of the photo. The photo is scaled according to the aspect ratio. The value `0` leaves the photo in its original resolution. The photo is never scaled up.
`quality`	`number`	The image quality on a scale from 10 (highest compression) to 100 (best quality).

PhotopickerResponse

Prop	Type	Description
`selected`	`boolean`	Shows whether the user has selected photos (`true`) or not (`false`).
`urls`	`string[]`	The URIs of the selected and converted photos. This might contain empty elements for errornous photos.

Implementation

The exciting parts of the source code for Android can be found here. The ones for iOS are here.

License

MIT

Usage no npm install needed!