Animated¶

PythonNative's Animated API mirrors React Native's. Build performant animations declaratively by binding AnimatedValue instances to the style of an Animated.View, Animated.Text, or Animated.Image. The reconciler holds a ref to the underlying native view; the animation driver pushes value changes directly to the native handler's set_animated_property hook so per-frame updates bypass full reconciliation.

Animated values + animation drivers + animated component wrappers.

Modeled on React Native's Animated API but with an async-aware completion contract. The core primitives are:

AnimatedValue: a numeric cell with subscribers; animations mutate it over time.
Animated.timing / Animated.spring / Animated.decay: animation factories. The objects they return implement __await__, so you can write await Animated.timing(v, to=1.0) to suspend until the animation finishes.
Animated.sequence / Animated.parallel / Animated.delay: composition; also awaitable.
Animated.View / Animated.Text / Animated.Image: components whose style may contain AnimatedValue instances.

Driver:

A single background thread ticks at ~60 Hz, advancing every active animation by dt.
Animations expose two APIs:
handle.start() — fire-and-forget. Returns self.
await handle (or await handle.run()) — wait for the animation to complete; cancellation cancels the animation.

Example

import pythonnative as pn


@pn.component
def FadeIn():
    opacity = pn.use_animated_value(0.0)

    async def fade_in():
        await pn.Animated.timing(opacity, to=1.0, duration=400)
        await pn.Animated.timing(opacity, to=0.5, duration=200)

    pn.use_async_effect(fade_in, [])

    return pn.Animated.View(
        pn.Text("Hello!"),
        style={"opacity": opacity, "padding": 20},
    )

Classes:

Name	Description
`AnimatedValue`	A subscribable numeric cell driven by animations.

Functions:

Name	Description
`use_animated_value`	Return an `AnimatedValue` that is stable across renders.

Attributes:

Name	Type	Description
`Animated`

Animated `module-attribute` ¶

Animated = _AnimatedNamespace()

AnimatedValue ¶

AnimatedValue(initial: float = 0.0)

A subscribable numeric cell driven by animations.

Direct mutation via set_value fires subscribers immediately; animations call set_value from the ticker thread.

Subscribers are (prop_name, callback) tuples. Each animated component (e.g., Animated.View) subscribes once per AnimatedValue prop in its style during mount.

Methods:

Name	Description
`set_value`	Set the value immediately and fire all subscribers.
`add_listener`	Register `callback` for changes to this value.

Attributes:

Name	Type	Description
`value`	`float`	Return the current numeric value (without subscribing).

value `property` ¶

value: float

Return the current numeric value (without subscribing).

set_value ¶

set_value(new_value: float) -> None

Set the value immediately and fire all subscribers.

add_listener ¶

add_listener(prop: str, callback: Callable[[float], None]) -> Callable[[], None]

Register callback for changes to this value.

Returns an unsubscribe callable. prop is metadata only — it lets the subscriber differentiate this binding from others on the same AnimatedValue.

use_animated_value ¶

use_animated_value(initial: float = 0.0) -> AnimatedValue

Return an AnimatedValue that is stable across renders.

Convenience wrapper for the common pattern pn.use_memo(lambda: AnimatedValue(initial), []). The same instance is returned on every render of the same component, so you can drive it from event handlers without recreating it.

Parameters:

Name	Type	Description	Default
`initial`	`float`	The starting numeric value.	`0.0`

Returns:

Type	Description
`AnimatedValue`	A mount-stable `AnimatedValue`.