nativescript-imagepicker

NativeScript Image Picker

Imagepicker plugin supporting both single and multiple selection.
Plugin supports iOS8+ and uses Photos Framework.
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. See demo for implementation details.

• Installation
• Configuration
• Migrating from 4.x.x to 5.x.x
• Migrating from 3.x.x to 4.x.x
• Usage
  • Import the plugin
  • Create imagepicker
  • Request permissions, show the images list and process the selection
• API
  • Methods
  • Properties
  • Image properties
• Contribute
• Get Help

Installation

In Command prompt / Terminal navigate to your application root folder and run:

tns plugin add nativescript-imagepicker
tns run

Configuration

No additional configuration required!

Migrating from 4.x.x to 5.x.x

With version 5.x.x major update to the plugin there is a related dependency which needs to be updated inside your project. The plugin uses internally the nativescript-ui-listview plugin (part of the NativeScript Pro UI components). Recently the monolithic NativeScript Pro UI plugin was split in multiple plugins, each of them representing a single component. Now, instead of the monolithic package, nativescript-imagepicker uses only the component it needs. To use version 5.x.x of the plugin, you need to update any dependencies to nativescript-pro-ui in your project with the single component alternatives as described in the migration guide.

Migrating from 3.x.x to 4.x.x

With the 4.x.x major update to the plugin there is a related dependency which needs to be updated inside your project. The plugin uses internally the nativescript-pro-ui plugin (previously known as nativescript-telerik-ui) which has bee updated and made 100% free. This means that if your project is using the deprecated nativescript-telerik-ui/pro plugins adding the latest version of the nativescript-imagepicker plugin will cause your project to throw an build error when working with iOS. This is because the nativescript-imagepicker has a dependency to the new nativescript-pro-ui plugin and when your project also depends on the old nativescript-telerik-ui plugin there is a native frameworks collision.

In order to solve this you simply have to update to the latest nativescript-pro-ui, more details on how to migrate from nativescript-telerik-ui/pro to nativescript-pro-ui can be found here.

Usage

The best way to explore the usage of the plugin is to inspect both demo apps in the plugin repository. In demo folder you can find the usage of the plugin for TypeScript non-Angular application. Refer to demo/app/main-page.ts. In demo-angular is the usage in an Angular app. Refer to demo-angular/app/app.component.ts.

In addition to the plugin usage, both apps are webpack configured.

In short here are the steps:

Import the plugin

TypeScript

import * as imagepicker from "nativescript-imagepicker";

Javascript

var imagepicker = require("nativescript-imagepicker");

Create imagepicker

Create imagepicker in single or multiple mode to specifiy if the imagepicker will be used for single or multiple selection of images

TypeScript

let context = imagepicker.create({
    mode: "single" // use "multiple" for multiple selection
});

Javascript

var context = imagepicker.create({ mode: "single" }); // use "multiple" for multiple selection

Request permissions, show the images list and process the selection

context
    .authorize()
    .then(function() {
        return context.present();
    })
    .then(function(selection) {
        selection.forEach(function(selected) {
            // process the selected image
        });
        list.items = selection;
    }).catch(function (e) {
        // process error
    });

NOTE: To request permissions for Android 6+ (API 23+) we use nativescript-permissions.

API

Methods

• create(options) - creates instance of the imagepicker. Possible options are:

Option	Platform	Default	Description
mode	both	multiple	The mode if the imagepicker. Possible values are single for single selection and multiple for multiple selection.
doneText	iOS	Done	The text of the "Done" button on top right.
cancelText	iOS	Cancel	The text of the "Cancel" button on top left.
albumsText	iOS	Albums	The title of the "Albums" screen from where the selection of album and images can be done.
newestFirst	iOS	false	Set to true to sort the images in an album by newest first.

• authorize() - request the required permissions.
• present() - show the albums to present the user the ability to select images. Returns an array of the selected images.
• cancel() - cancel selection. iOS only.
• done() - confirm the selection is ready. iOS only.

Properties

Property	Default	Description
selection	null	An array of selected image assets.
albums	null	Albums from where the images are picked.

Image properties

Once image is picked some options can be applied to it before it is used:

Option	Default	Description
maxWidth	null	Image max width
maxHeight	null	Image max height
aspectRatio	fit	iOS only. Possible values are fit and fill. Read more

Contribute

We love PRs! Check out the contributing guidelines. If you want to contribute, but you are not sure where to start - look for issues labeled help wanted.

Get Help

Please, use github issues strictly for reporting bugs or requesting features. For general questions and support, check out the NativeScript community forum or ask our experts in NativeScript community Slack channel.