Image

Image

Use Image to render bitmaps with optional loading and error states. Image supports resolution-independent assets via @res in URIs.

Try It

Run the snippet: the left image loads from the packaged app using @res. The right image shows how to adapt a remote URL by wrapping it with resolveImageUri().

Resolution-Independent Assets with @res

• Packaged assets (pkg:/...): On Roku, the manifest enables automatic @res substitution. Put @res before the extension, e.g., button@res.png, and include -sd, -hd, -fhd variants. For web, Hosanna normalizes pkg:/ paths.
• Remote/web URLs: @res is also substituted automatically, e.g. http://example.com/image@res.png will become http://example.com/image-fhd.png, on a fhd device, and http://example.com/image-hd.png on an hd device.

Tip: Use @res for One URI

Name your images with -sd, -hd, and -fhd in the name. Reference a single @res URI throughout your code and styles.

⚙️ Key Props & Methods

Key Props

• imageUri: The image URI. Supports pkg:/... and HTTP(S).
• loadingBitmapUri: URI shown while loading.
• failedBitmapUri: URI shown on failure.
• loadingBitmapOpacity / failedBitmapOpacity: Opacity for the respective states.
• color: Blend color tint (hex RGBA or theme color).
• loadDisplayMode: LimitSize (default) and other native renderer modes.
• onLoadStatusChange(event): Callback when load status changes.

Remote URLs: resolveImageUri

resolveImageUri(uri: string): string normalizes pkg:/ and replaces @res with a concrete suffix. Use it for HTTP(S) URLs:

import { resolveImageUri } from '../../../hosanna-ui/lib/image-utils';

const remote = resolveImageUri('https://cdn.example.com/img/promo@res.jpg');
// => 'https://cdn.example.com/img/promo-fhd.jpg' (current mapping)

Current Mapping

The current implementation maps @res to -fhd. On Roku, packaged assets still auto-substitute per the manifest. Remote URL mapping may evolve to use device resolution.

Nine-Patch Support

Hosanna supports nine‑patch PNGs (.9.png). Use @res with nine‑patch the same way: border@res.9.png.