View on GitHub

@nativescript/imagepicker ​

Contents ​

• Intro
• Installation
  • Android required permissions
  • iOS required permissions
• Pick images
  • Demo
• API
  • ImagePicker class
  • create()
  • Options
  • ImagePickerMediaType

Intro ​

Imagepicker plugin supporting both single and multiple selection.

• Plugin supports iOS8+ and uses QBImagePicker cocoapod.
• For Android it uses Intents to open the stock images or file pickers. For Android 6 (API 23) and above, the permissions to read file storage should be explicitly required.

Installation ​

Install the plugin by running the following command in the root directory of your app.

npm install @nativescript/imagepicker

Note: Version 3.1 contains breaking changes:

• New behavior on iOS when the user selects Limit AccessLim.. detailed in iOS Limited permission.

Note: Version 3.0 contains breaking changes:

• authorize() now returns a Promise<AuthorizationResult> for both android and ios.
• In the returned result from present() each result[i].thumbnail is now an ImageSource.
• result[i].duration is now typed correctly as a number.

Note: Version 2.0 contains breaking changes. In order supply more information about your selection, the ImageSource asset is nested in the response so you'll need to update your code to use result.asset instead of result as your src for your Images.

Android required permissions ​

Add the following permissions to the App_Resources/Android/src/main/AndroidManifest.xml file:

• targetSdkVersion < 33

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

<application android:requestLegacyExternalStorage="true" ... >
    ...
  </application>

• targetSdkVersion >=33(Android 13+)

These are only required when not setting android.use_photo_picker = true.

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

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

See the complete example here.

Android Photo picker ​

For phones running android 13+ specifying the option android.use_photo_picker = true when creating the ImagePicker will result in the use of the System Photo Picker.

let imagePickerObj: ImagePicker = imagePickerPlugin.create({
  mode: 'single',
  android: { use_photo_picker: true },
})

This means you can remove the READ_MEDIA_IMAGES, READ_MEDIA_VIDEO permissions and do not have to prompt the user for permission.

Full details here.

You can also now limit the number of images that are selectable in the Photo Picker by specifying the maximumNumberOfSelection option.

For phones running < Android 13, this use_photo_picker option has no effect.

iOS required permissions ​

Using the plugin on iOS requires the NSPhotoLibraryUsageDescription permission. Modify the app/App_Resources/iOS/Info.plist file to add it as follows:

<key>NSPhotoLibraryUsageDescription</key>
<string>Description text goes here</string>

Apple App Store might reject your app if you do not describe why you need this permission. The default message Requires access to photo library. might not be enough for the App Store reviewers.

iOS Limited permission ​

Apple introduced the PHAuthorizationStatusLimited permission status with iOS 14, this is where the user specifies that the app can only access specified photos by choosing the Limit Access.. option in the authorization dialog.

In this case authorise() will return an AuthorizationResult where authorized will be true and the details will contain 'limited'.

Every time the app is launched anew, and the authorize method is called, if the current permission is limited the user will be prompted to update the image selection.

To prevent this prompt, add the following values to your App_Resources/iOS/Info.plist:

<key>PHPhotoLibraryPreventAutomaticLimitedAccessAlert</key>
<true/>

Pick images ​

To pick images (and/or videos) with the plugin, take the steps below:

1. Import the plugin

import * as imagePickerPlugin from '@nativescript/imagepicker'

2. Instantiate the picker with selection mode

Instantiate the picker with selection mode by calling the create funciton of the plugin passing it an object that specifies mode(single or multiple) of media assets selection.

let imagePickerObj: ImagePicker = imagePickerPlugin.create({
  mode: 'single',
})

3. Pick the images

• Request for permission Request for permission to access photo library by calling the asynchronous authorize method.
• Present the list of media assets If authorization request promise has resolved(e.i. the user has granted the permission), present the list of media assets to be picked from by calling the present method.
• Process the selection The present method resolves with the selected media assets that can you to process and consume.

imagePickerObj
  .authorize()
  .then((authResult) => {
    if (authResult.authorized) {
      return imagePickerObj.present().then(function (selection) {
        selection.forEach(function (selected) {
          this.imageSource = selected.asset
          this.type = selected.type
          this.filesize = selected.filesize
          //etc
        })
      })
    } else {
      // process authorization not granted.
    }
  })
  .catch(function (e) {
    // process error
  })

Demo ​

You can play with the plugin on StackBlitz at any of the following links:

• NativeScript TypeScript
• NativeScript Angular
• NativeScript Vue
• NativeScript Svelte

API ​

ImagePicker class ​

The class that provides the media selection API. It offers the following methods:

Options ​

An object passed to the create method to specify the characteristics of a media selection.

ImagePickerMediaType ​

The type of media assets to be selected.

• Any = 0,
• Image = 1,
• Video = 2

License ​

Apache License Version 2.0