Poster

Poster is a renderable node that displays bitmap images

import { Poster } from "@roku-sdk/components";

Poster(props: IPosterProps): JSX.Element

Description

Poster is a renderable node that displays bitmap images. It is one of the most widely used nodes in SceneGraph applications for displaying images, thumbnails, and graphics with support for scaling, loading states, and fallback images.

Images can be imported directly in TypeScript, which provides automatic resolution handling and dimension information. See the Static Image Management documentation for details.

Attribute ordering pitfall: When using <poster> as a JSX intrinsic, write event handlers (onLoadStatus, etc.) before uri and other props that trigger synchronous events on assignment. If uri is set first and the image is already cached, the load event fires before your handler is registered and is silently dropped. Writing handlers first is good practice regardless.

// Wrong: onLoadStatus may be missed if image is cached
<poster uri={src} onLoadStatus={handleLoad} />

// Correct: handler registered before the prop that fires it
<poster onLoadStatus={handleLoad} uri={src} />

Parameters

Example

// Import image with resolution substitutes - note uri is last
import { uri as logo } from "./images/logo-*.png";
<poster width={200} height={100} uri={logo} />

// Use static URI path - note uri is last
<poster width={1920} height={1080} uri="pkg:/images/background.jpg" />

Types

IPosterProps

Properties for the Poster node.

Poster is a renderable node that displays bitmap images. It is one of the most widely used nodes in SceneGraph applications for displaying images, thumbnails, and graphics with support for scaling, loading states, and fallback images.

Images can be imported directly in TypeScript, which provides automatic resolution handling and dimension information. See the Static Image Management documentation for details.

Example

// Import image with resolution substitutes
import { uri as logo } from "./images/logo-*.png";
<Poster width={200} height={100} uri={logo} />

// Use static URI path
<Poster width={1920} height={1080} uri="pkg:/images/background.jpg" />

Extends IGroupProps.

IPosterProps.loadDisplayMode

Specifies how the bitmap should be scaled to fit the poster dimensions.

• "noScale": Bitmap loaded at original resolution. If Poster's width/height differ, it will be scaled to fill (aspect ratio not preserved)
• "scaleToFit": Scale to fit within dimensions, preserving aspect ratio with letterboxing/pillarboxing
• "scaleToFill": Stretch to fill dimensions, distorting if aspect ratios differ
• "scaleToZoom": Scale to fill dimensions, preserving aspect ratio but cropping parts of the image
• "limitSize": Scale while loading so max width/height doesn't exceed loadWidth/loadHeight, preserving aspect ratio

IPosterProps.onLoadStatus

Event handler called when the load status changes.

• "none": No load operation in progress
• "loading": Image is currently loading
• "ready": Image loaded successfully
• "failed": Image failed to load

IPosterProps.uri

Specifies the URI of the bitmap image file to be displayed. Can use static paths (e.g., "pkg:/images/icon.png") or imported URIs from TypeScript. Images included as part of the application package can be referenced using the pkg:/images prefix.

Important: Set uri as the last property in your JSX to avoid timing issues. If the image is already cached or loads quickly from local storage, it may render before other properties (such as loadDisplayMode or event handlers) are applied. Placing uri last ensures all configuration properties are set before the image loading process begins.

BitmapMargins

PosterLoadStatus

type PosterLoadStatus = "none" | "loading" | "ready" | "failed";