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. The core primitives are:

• AnimatedValue: a numeric cell with subscribers; animations mutate it over time.
• Animated.timing / Animated.spring / Animated.decay: animation factories.
• Animated.sequence / Animated.parallel / Animated.delay: composition.
• Animated.View / Animated.Text / Animated.Image: components whose style may contain AnimatedValue instances. The component subscribes to the value during mount and forwards changes directly to the underlying native handler's set_animated_property hook (bypassing the reconciler so per-frame work doesn't go through full Python reconciliation).

Driver:

• A single background thread ticks at ~60 Hz, advancing every active animation by dt. When an animation finishes it removes itself from the active set; the thread sleeps when nothing is running.
• For platforms that have a native easing/animation API, AnimatedValue also sends a one-shot set_animated_property(view, prop, target, duration_ms, easing) call when the animation starts, so UIKit / Android can interpolate at GPU 60 Hz without per-frame Python work. The Python ticker then keeps the reactive AnimatedValue.value reading approximately synchronized for any non-native consumers.

Example

import pythonnative as pn

@pn.component
def FadeIn():
    opacity = pn.use_memo(lambda: pn.Animated.Value(0.0), [])

    def fade_in():
        pn.Animated.timing(opacity, to=1.0, duration=400).start()

    pn.use_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.

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.

Used by user code for instant snaps; animations also call this once per tick to update the value.

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 (the value can be bound to multiple props on multiple views).

See also

• The Animations guide walks through fade-ins, springs, sequences, and gesture-driven animations.
• use_ref explains the ref semantics that back Animated.View.