Tween
Available since @roku-sdk/components 2.18.0
import { Tween } from "@roku-sdk/components";Tween(props: TweenProps): JSX.ElementDescription
Tween — description pending.
Parameters
| Name | Type | Description |
|---|---|---|
props | TweenProps |
Types
TweenProps
Unified <tween> primitive.
Animate a target node using the unified native field contract.
One component presenting the unified tween field contract, replacing the four earlier tween wrappers (Tween/GridTween, TweenFloat, FloatTween, ScaleTween). On device it renders a <tween> element, which is the firmware's native node when roku.hasFeature("tween") reports support. Otherwise @roku-sdk/compat aliases the tag to its RsgTweenShim; without compat creating it throws an error naming the missing feature. A renderer that provides its own tween implementation aliases this module to it at build time.
| Name | Type | Description |
|---|---|---|
onAnimationState? | (state: AnimationState, value: number | Vector2D) => void | Called with separate state and value arguments, unlike the intrinsic's tuple event. |
targetNode? | unknown | Node reference to animate, or a getter returning it. Takes precedence over targetRef. |
targetRef? | unknown |
Extends Omit<ITweenProps, "targetNode" | "onAnimationState">.
ITweenProps
Properties for the Tween node — the unified declarative animation primitive.
A <tween> animates a single field on a target node. On Roku it is a native node, which supersedes the earlier BrightScript/XML tween components and takes the interpreter out of the animation hot path. Application source writes <tween> and gets render-thread animation without branching on where it runs.
The portable subset of the fields below — the properties every renderer honours, and the ones portable code may rely on — is frozen as ITweenCoreProps in core-props.ts. This interface is the full SceneGraph surface and is a superset of that base.
Example
// Slide a node to x=480 over the default duration
<tween targetNode={ref} field="translation" targetVector={[480, 0]} />| Name | Type | Description |
|---|---|---|
axis? | "x" | "y" | "all" | For vector fields, which axis to animate. "x" and "y" animate one component and hold the other at preserveOther to avoid stale mid-flight reads; "all" animates the whole vector. |
control? | AnimationControl | Optional explicit playback control (start/stop/pause/resume/finish). |
duration? | number | Duration in seconds. 0 is an instant snap with no animation artifacts. |
easeFunction? | EaseFunction | Named easing function. |
field? | string | Field on targetNode to animate. |
onAnimationStart? | (t: [second, millisecond]) => void | Output: [second, millisecond] render-thread timestamp at animation start. |
onAnimationState? | (t: [state, value]) => void | Output: [state, value] on each animation state transition, where value is the target field's current value: a number for a float field, a Vector2D ([x, y]) for a vector2d field such as the default translation. Delivered as one array, like the other outputs. |
onAnimationStop? | (t: [index, position, stopTime]) => void | See below. |
preserveOther? | number | Value held on the non-animated axis for single-axis vector animation. |
proposedStops? | number[] | [number, number][] | Candidate snap positions for velocity-preserving settle. Empty means no settle. Float fields and single-axis vector motion take scalar candidates; whole-vector motion takes [x, y] pairs. Wrong-shaped entries are skipped and logged, and reported indices refer to the original list. A list with no usable candidates does not settle. |
targetNode? | DomNode | The node whose field is animated. If you render <tween> directly, clear targetNode before removing it: a shim removed while idle or paused otherwise leaves its Animation in the parent. The Tween wrapper does this for you. |
targetValue? | number | Float target. Writing it starts the animation. A scalar written against a vector2d field auto-expands to [v, v] on axis="all"; documented sugar for a uniform scale, not the canonical form. There is no separate Y target, so use targetVector for an [x, y] move; a vector target on a vector field is the plain way to say "all". |
targetVector? | [number, number] | Vector2d target [x, y]. Writing it starts the animation. |
Extends INodeProps.
ITweenProps.onAnimationStop
Output: [index, position, [second, millisecond]] after a settle re-arm — which proposedStops candidate was chosen, the coordinate it settles to, and the render-thread timestamp the settle is expected to finish at. On a vector field position is a scalar: the owned coordinate under "x"/"y", and under "all" the coordinate of the chosen point that travels further. Read the full point from proposedStops[index].
Note this is NOT the plain <animation> node's [second, millisecond] stop timestamp. A tween's stop event is only interesting for what it settled on, so the chosen index and position lead and the timestamp is nested last.
Updated about 3 hours ago