PosterGrid

PosterGrid is a simple grid class that can be used to display two-dimensional grids of posters

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

PosterGrid(props: IPosterGridProps): JSX.Element

Description

PosterGrid is a simple grid class that can be used to display two-dimensional grids of posters. In addition to the poster, each item in the grid can include up to two lines of captions.

The number of columns in the PosterGrid is fixed and the number of rows varies. The items in the grid fill each row from left to right, then top to bottom.

Parameters

Example

<posterGrid
    basePosterSize={[240, 240]}
    itemSpacing={[32, 32]}
    caption1NumLines={1}
    caption2NumLines={1}
    numColumns={4}
    numRows={3}
    content={gridContent}
    onItemSelected={(index) => handleSelection(index)}
/>

Types

IPosterGridProps

Properties for the PosterGrid node.

PosterGrid is a simple grid class that can be used to display two-dimensional grids of posters. In addition to the poster, each item in the grid can include up to two lines of captions.

The number of columns in the PosterGrid is fixed and the number of rows varies. The items in the grid fill each row from left to right, then top to bottom.

The layout of rows and columns in the grid is very flexible. Possible layouts include:

• A simple layout with all posters in the grid having the same size
• A layout with posters in some rows having varying heights and/or columns having varying widths
• A layout with varying width rows and columns and items that occupy one or more rows and columns

The grid items can be organized into sections that are demarcated by labelled horizontal divider lines between the sections.

Example

<PosterGrid
    basePosterSize={[240, 240]}
    itemSpacing={[32, 32]}
    caption1NumLines={1}
    caption2NumLines={1}
    numColumns={4}
    numRows={3}
    content={gridContent}
    onItemSelected={(index) => handleSelection(index)}
/>

Extends IArrayGridProps.

IPosterGridProps.basePosterSize

Specifies the width and height of the posters in the grid.

For simple layouts, set this to the dimensions of each poster image. Can be overridden per-row with rowHeights or per-column with columnWidths.

IPosterGridProps.caption1NumLines

Specifies the number of lines to render for the grid item first caption.

Set to 0 to hide the first caption.

IPosterGridProps.caption2NumLines

Specifies the number of lines to render for the grid item second caption.

Set to 0 to hide the second caption.

IPosterGridProps.captionHorizAlignment

Specifies the horizontal positioning of the grid item captions.

• left: Left-justify the caption relative to the grid item poster
• center: Center-justify the caption relative to the grid item poster
• right: Right-justify the caption relative to the grid item poster

Set enableCaptionScrolling to false to use captionHorizAlignment.

IPosterGridProps.captionVertAlignment

Specifies the vertical positioning of the grid item captions.

• above: Position caption so bottom lies just above the poster
• top: Align top of caption with top edge of poster
• center: Align vertical center of caption with center of poster
• bottom: Align bottom of caption with bottom edge of poster
• below: Position caption so top lies just below the poster

IPosterGridProps.content

Specifies the content for the grid.

Should be a ContentNode with child nodes for each item in the grid. If the data contains section markers, section dividers will be drawn between each section. These section dividers may contain an icon and/or a string.

IPosterGridProps.imageWellBitmapUri

Specifies the bitmap file to use to suggest where images would appear for empty grids and empty sections of grids.

Only set this field to specify a custom bitmap that differs from the default.

IPosterGridProps.loadingBitmapUri

Specifies a bitmap file to display while a grid item's poster is loading.

To execute a seamless cross-fade transition between posters, set this to the URI of the currently displayed poster.

IPosterGridProps.posterDisplayMode

Provides automatic scaling of posters when useAtlas is set to false.

If loading very large images (larger than UI resolution), you must set a scaling option other than noScale, otherwise the image may fail to load.

• noScale: No scaling applied
• scaleToFit: Scale to fit, preserving aspect ratio (letterboxing/pillarboxing)
• scaleToFill: Stretch to fill, distorting if aspect ratios differ
• scaleToZoom: Scale to fill, preserving aspect ratio but cropping

IPosterGridProps.useAtlas

Enables a performance optimization when most poster items have the same size.

When true, uses a texture atlas that stores the posters in the grid, providing rendering performance benefits for grids where most posters match basePosterSize.

Set to false for grids with:

• Complicated layouts with several posters differing from basePosterSize
• Only a few large posters (5-8, or about quarter screen height/width)

CaptionVertAlignment

Vertical alignment options for PosterGrid captions.

Extends the standard vertical alignment with additional positioning options specific to captions relative to the poster.

type CaptionVertAlignment = VertAlign | "above" | "below";