TargetList

TargetList extends TargetGroup with built-in focused/unfocused transitions and focus management policies, making it easy to create scrollable lists and rows with minimal scripting

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

TargetList(props: ITargetListProps): JSX.Element

Description

TargetList extends TargetGroup with built-in focused/unfocused transitions and focus management policies, making it easy to create scrollable lists and rows with minimal scripting.

It supports two focus modes:

• Fixed focus: the focused item stays in one position while items
  scroll beneath it.
• Floating focus: the focus moves across several positions before
  items begin to scroll.

Both modes can include an unfocusedTargetSet for a smooth layout transition when the list gains or loses focus.

Parameters

Example

import "./compiled-components/MyItem.xml";

<targetList
    itemComponentName="MyItem"
    focusedTargetSet={[
        <targetSet
            targetRects={[
                [0, -200, 1920, 200],
                [0, 20, 1920, 200],
                [0, 240, 1920, 400],
                [0, 660, 1920, 200],
                [0, 880, 1920, 200],
            ]}
            focusIndex={2}
        />,
    ]}
    unfocusedTargetSet={
        <targetSet
            targetRects={[
                [0, 0, 1920, 200],
                [0, 210, 1920, 200],
                [0, 420, 1920, 200],
                [0, 630, 1920, 200],
                [0, 840, 1920, 200],
            ]}
        />
    }
    content={contentNode}
    onItemFocused={(index) => console.log("Focused:", index)}
    onItemSelected={(index) => console.log("Selected:", index)}
/>

Types

ITargetListProps

Properties for the TargetList node.

TargetList extends TargetGroup with built-in focused/unfocused transitions, focus management policies (fixed focus, floating focus), and default key handling for navigating the list or row.

Fixed focus: Set focusedTargetSet to a single-element array containing one TargetSet. The focus stays fixed on the target rectangle at the TargetSet's focusIndex. Optionally set unfocusedTargetSet for a smooth transition when the list gains or loses focus.

Floating focus: Set focusedTargetSet to an array of TargetSets — one per focus position — with incrementing focusIndex values. As the user navigates, the list advances through the array until the last element is reached, at which point items begin to scroll.

Example

import { TargetList, TargetSet } from "@roku-sdk/components";
import "./compiled-components/MyItem.xml";

<TargetList
    itemComponentName="MyItem"
    focusedTargetSet={[
        <TargetSet
            targetRects={[
                [-178, -64, 240, 134],
                [72, -96, 360, 202],
                [442, -64, 240, 134],
                [692, -64, 240, 134],
            ]}
            focusIndex={1}
        />,
    ]}
    unfocusedTargetSet={
        <TargetSet
            targetRects={[
                [-100, -64, 240, 134],
                [150, -64, 240, 134],
                [400, -64, 240, 134],
                [650, -64, 240, 134],
            ]}
        />
    }
    content={contentNode}
/>

<TargetList
    itemComponentName="MyItem"
    advanceKey="right"
    reverseKey="left"
    focusedTargetSet={[
        <TargetSet targetRects={rectsForFocus0} focusIndex={0} />,
        <TargetSet targetRects={rectsForFocus1} focusIndex={1} />,
        <TargetSet targetRects={rectsForFocus2} focusIndex={2} />,
    ]}
    content={contentNode}
/>

Extends ITargetGroupProps.

ITargetListProps.focusedTargetSet

Specifies one or more TargetSets to be used when the TargetList has the focus.

• Fixed focus: provide a single-element array. Focus stays fixed on
  the target rectangle corresponding to the TargetSet's focusIndex
  (or the TargetGroup's defaultTargetSetFocusIndex if the TargetSet
  does not specify one).
• Floating focus: provide multiple TargetSets with incrementing
  focusIndex values. As the user presses advanceKey, focus floats
  from one TargetSet to the next until the last element is reached, at
  which point items begin to scroll. Reversing works symmetrically.