Skip to main content

Image

Image renders through the active platform's Poster adapter:

Image({
  imageUri: 'pkg:/assets/images/hero@res.jpg',
  width: 960,
  height: 540,
  loadDisplayMode: SGImageLoadDisplayMode.ScaleToFill,
  loadingBitmapUri: 'pkg:/assets/images/loading@res.png',
  failedBitmapUri: 'pkg:/assets/images/image-error@res.png',
  loadingBitmapOpacity: 1,
  failedBitmapOpacity: 1,
  retryCount: 2,
  retryDelayMs: 250,
  retryTimeoutMs: 5_000,
})
  .onLoadStatusChange((event) => {
    console.info('Image status', event.status);
  });

Fields​

  • imageUri: packaged, cache, temporary, or HTTP(S) image URI.
  • width and height: render and load dimensions.
  • color: Poster blend tint.
  • loadDisplayMode: the platform-compatible Poster display mode.
  • loadSync: request synchronous loading where the adapter supports it.
  • loadingBitmapUri / loadingBitmapOpacity.
  • failedBitmapUri / failedBitmapOpacity.
  • retryCount, retryDelayMs, and retryTimeoutMs.
  • onLoadStatusChange: receives the current SGImageLoadStatus.

Retries apply to failed or stuck loads. retryCount: 0 disables them.

pkg:/ and @res​

On Roku, packaged @res substitution is handled by the package/manifest convention. On web, Apple, and Android, the Poster adapters normalize the URI before loading:

  • pkg:/assets/images/card.png becomes /assets/images/card.png where appropriate; and
  • card@res.png currently becomes card-fhd.png.

The current helper uses -fhd for every non-Roku adapter; it does not yet pick -sd or -hd from device resolution.

Image({
  imageUri: 'https://cdn.example.com/cards/featured@res.jpg',
  width: 640,
  height: 360,
})

Image already passes its URI through the active adapter, so view code does not need to call resolveImageUri() first. Use the helper only when code outside an Image/Poster adapter must normalize an image path.

Nine-patch images

Nine-patch PNGs are supported. Keep the marker in the filename when combining it with @res, for example button@res.9.png.

Talk to us