Skip to content

Latest commit

 

History

History
310 lines (220 loc) · 8.32 KB

image.md

File metadata and controls

310 lines (220 loc) · 8.32 KB
title description contributors
Image
UI component for rendering images
rigor789
Ombuweb

<Image> is a UI component for rendering images. Images can be referenced by URL, resource URL (res://), base64 string, font resource (font://), ImageSource, and ImageAsset.

::: tip

Working with many images can quickly become a memory hog, for improved image handling it's recommended to use an Image caching library. Here are a few plugins from our community:

:::

<<< @/../examples/typescript/src/ui/Image/template.xml#example

<<< @/../examples/angular/src/ui/Image/component.html#example

<<< @/../examples/react/src/components/ui/image.tsx#example

<<< @/../examples/solid/src/ui/image.tsx#example

<<< @/../examples/svelte/app/components/ui/Image.svelte#example

<<< @/../examples/vue/src/ui/Image/component.vue#example

Examples

Displaying images from App_Resources

To display images from platform specific locations (App_Resources/Android/drawable-XXX/, or App_Resources/iOS/) prefix the source with res://.

<Image src="res://icon" />

Displaying images from the src/assets directory

By default all assets placed in the src/assets directory (create the directory if it's not present) will be copied to the correct native platform location to be bundled with the app. To reference these images, prefix them with the ~ character, which is an alias pointing to the src folder.

<Image src="~/assets/logo.png" />

Displaying images from URLs

Images can be displayed from remote URLs. Depending on the software version of the device, insecure URLs may be blocked (http://), it's recommended to always use secure URLs (https://).

<Image
  src="https://art.nativescript.org/logo/export/NativeScript_Logo_Blue_White.png"
/>

Displaying base64-encoded images

Images can be displayed from base64 encoded strings.

<Image src="data:Image/png;base64,iVBORw..." />

Rendering font icons as images

Font symbols can be rendered as an image by prefixing the source with font:// and setting the correct font-family via eg. a CSS class:

<Image src="font://&#xf004;" class="fas" />
.fas {
  font-family: 'Font Awesome';
  /* ... */
}

Using SF Symbols on iOS (8.8+)

Images can also be used to display SF Symbols on iOS by using the sys:// prefix along with the symbol name. These also support iosSymbolEffect for animated effects as well as iosSymbolScale with a possible value of small|medium|large;

<GridLayout rows="auto,auto" columns="*,*">
  <image
    src="sys://photo.on.rectangle.angled"
    tintColor="green"
    [iosSymbolEffect]="symbolBounceEffect"
  />

  <image
    col="1"
    src="sys://photo.on.rectangle.angled"
    tintColor="green"
    [iosSymbolEffect]="symbolBounceEffect"
    iosSymbolScale="small"
  />

  <image
    row="1"
    src="sys://photo.on.rectangle.angled"
    tintColor="green"
    [iosSymbolEffect]="symbolBounceEffect"
    iosSymbolScale="medium"
  />

  <image
    row="1"
    col="1"
    src="sys://photo.on.rectangle.angled"
    tintColor="green"
    [iosSymbolEffect]="symbolBounceEffect"
    iosSymbolScale="large"
  />
</GridLayout>
import { ImageSymbolEffects } from '@nativescript/core'

const symbolBounceEffect = ImageSymbolEffects.Bounce
<iframe style="width: 100%; min-height: 200px; aspect-ratio: 16 / 9;" src="https://www.youtube.com/embed/y_ULvYe5mTA" title="SF Symbol usage with NativeScript" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

This demonstrates using various built-in presets for effects and also using the iosSymbolScale property which is useful when you apply affects so the animation doesn't exceed the bounds of it's Image container (as can be seen in the top left usage in the video).

Custom Symbol Effects

You can also create custom effects using the full expansive iOS symbol API, for example:

import { ImageSymbolEffect } from '@nativescript/core'

const effect = new ImageSymbolEffect(NSSymbolBounceEffect.effect())
effect.options =
  NSSymbolEffectOptions.optionsWithSpeed(2).optionsWithRepeatCount(6)
effect.completion = (context) => {
  console.log('effect completed!', context)
}
const customSymbolEffect = effect
<image
  src="sys://heart.fill"
  tintColor="red"
  [iosSymbolEffect]="customSymbolEffect"
/>
<iframe style="width: 100%; min-height: 200px; aspect-ratio: 16 / 9;" src="https://www.youtube.com/embed/IuyGBoqJNKo" title="SF Symbol custom effects with NativeScript" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

Props

src

src: string | ImageSource | ImageAsset

Gets or sets the source.

A string can be a http://, https://, res://, font:// or an absolute path (eg. ~/assets/image.png).

See ImageSource and ImageAsset.

imageSource

imageSource: ImageSource

Gets or sets the source from an ImageSource instance.

See ImageSource.

tintColor

tintColor: Color | string

Sets a color to tint the image.

See Color.

stretch

stretch: ImageStretchType // "none" | "aspectFill" | "aspectFit" | "fill"

Gets or sets the way the image is resized to fill its allocated space.

See ImageStretchType

iosSymbolEffect (8.8+)

iosSymbolEffect: ImageSymbolEffect | ImageSymbolEffects

Gets or sets the effect of the SF Symbol. You can create your own custom ImageSymbolEffect or use presets defined from ImageSymbolEffects, for example:

export enum ImageSymbolEffects {
  Appear = 'appear',
  AppearUp = 'appearUp',
  AppearDown = 'appearDown',
  Bounce = 'bounce',
  BounceUp = 'bounceUp',
  BounceDown = 'bounceDown',
  Disappear = 'disappear',
  DisappearDown = 'disappearDown',
  DisappearUp = 'disappearUp',
  Pulse = 'pulse',
  Scale = 'scale',
  ScaleDown = 'scaleDown',
  ScaleUp = 'scaleUp',
  VariableColor = 'variableColor',
  Breathe = 'breathe',
  BreathePlain = 'breathePlain',
  BreathePulse = 'breathePulse',
  Rotate = 'rotate',
  RotateClockwise = 'rotateClockwise',
  RotateCounterClockwise = 'rotateCounterClockwise',
  Wiggle = 'wiggle',
  WiggleBackward = 'wiggleBackward',
  WiggleClockwise = 'wiggleClockwise',
  WiggleCounterClockwise = 'wiggleCounterClockwise',
  WiggleDown = 'wiggleDown',
  WiggleForward = 'wiggleForward',
  WiggleUp = 'wiggleUp',
  WiggleLeft = 'wiggleLeft',
  WiggleRight = 'wiggleRight',
}

Keep in mind that some are only iOS 17 or 18 and above.

iosSymbolScale (8.8+)

iosSymbolScale: number

Gets or sets the scale of the SF Symbol.

loadMode

loadMode: 'sync' | 'async'

Gets or sets the loading strategy for the images.

Default value: async.

Valid values:

  • sync - blocks the UI if necessary to display immediately. Only recommeded for small images like icons.
  • async - loads in the background, the image may appear with a short delay, good for large images.

Note: When loading images from the web, they are always loaded async.

...Inherited

For additional inherited properties, refer to the API Reference.

Native component