NativeScript Core

Image

The Image widget shows an image in your mobile application. In a NativeScript application images are added to an application either declaratively (XML) or with code. We can load the image from an ImageSource or a URL using the src property. Behind the Image module stands UIImage on iOS and android.widget.ImageView on Android. As working with images is an essential part of each mobile application following the best practices is a must.

Basics

The prefix of the src value specifies where the image will be loaded form. The possible options are:

Using Resources

Using the res:// prefix you can load a resource image. This is the suggested approach, as it uses the native methods for loading the best image for the current device screen density and resolution.

Loading an image from application resources (in App_Resources/<platform>).

<Image src="res://icon" stretch="aspectFill" />
const newImage = new Image();
newImage.src = "res://icon";
newImage.stretch = "aspectFill";

Using Local Files

Using the ~/ prefix, you can load images relative to the App folder inside your project.

Loading an image from the local file system. In the example below the full path of the image is <project-folder>/app/images/logo.png

<Image src="~/images/logo.png" stretch="aspectFill" />

Using Online Resources

Web images have an http:// or https:// prefix. When such an image is loaded, an asynchronous http request will be sent and the image will be shown if the request is successful.

Loading an image from URL. For large images use loadMode property to avoid blocking of the UI (see the best practices article for more information)

<Image src="https://docs.nativescript.org/img/cli-getting-started/angular/chapter0/NativeScript_logo.png" stretch="aspectFill" />

Improve this document

Demo Source


Binding

Common scenario would be to bind the src property to a dynamically received value.

Loading an image with src property binding.

<Image src="{{ imageUri }}" width="100" height="100" stretch="aspectFill" />
const vm = new Observable();
vm.set("imageUri", "~/images/logo.png");
page.bindingContext = vm;

Improve this document

Demo Source


Image Source

We can use the image-source module to create an image source and manually set it to the image.

const image = new Image();
const imageSource = imageSourceModule.fromResource("logo");
image.imageSource = imageSource;
image.height = 300;
image.stretch = "aspectFill";

Common scenario when working with images is to convert them to and from Base64 encoded string. In NativeScript converting is achieved by using toBase64String and fromBase64 methods from image-source module. Then create an ImageSource instance and bind it to the source property of Image.

Improve this document

Demo Source


Stretching

The stretch functionality allows us to describe how content is resized to fill its allocated space. The available options for this property are as follow:

  • none - The image preserves its original size
<Image src="~/images/logo.png" stretch="none" />
  • fill - The image is resized to fill the destination dimensions. In this case, the aspect ratio is not preserved.
<Image src="~/images/logo.png" stretch="fill" />
  • aspectFit - The image is resized to fit the destination dimensions while it preserves its native aspect ratio. If the aspect ratio of the destination rectangle differs from the image, the image will be clipped to fit in the destination.
<Image src="~/images/logo.png" stretch="aspectFill" />
  • aspectFill - Tthe image is resized to fill in the destination dimensions while it preserves its native aspect ratio.
<Image src="~/images/logo.png" stretch="aspectFit" />

Note: The default value for this property is aspectFit.

Improve this document

Demo Source


API Reference for

Native Component

Android iOS
android.widget.ImageView UIImageView

See Also Android Image Optimization