Hooks¶

Hook primitives for @component functions: state, effects, memoization, context, and refs. Hooks must be called at the top level of a component (not inside conditionals or loops) so they can be matched to the same slot across renders.

Hook primitives for function components.

Provides React-like hooks for managing state, effects, memoization, context, and navigation within function components decorated with component. Hooks must be called at the top level of a component (not inside conditionals or loops) so they map to the same slot across renders.

Effects are queued during the render phase and flushed after the reconciler commits native-view mutations. This ordering guarantees that effect callbacks can safely measure layout or interact with the committed native tree.

Example

import pythonnative as pn

@pn.component
def Counter(initial=0):
    count, set_count = pn.use_state(initial)
    return pn.Column(
        pn.Text(f"Count: {count}"),
        pn.Button("+", on_click=lambda: set_count(count + 1)),
    )

Classes:

Name	Description
`HookState`	Per-instance storage for one component's hooks.
`Context`	Container for a value shared across a subtree.
`NavigationHandle`	Handle returned by `use_navigation`.

Functions:

Name	Description
`batch_updates`	Coalesce multiple state updates into a single re-render.
`use_state`	Return `(value, setter)` for component-local state.
`use_reducer`	Return `(state, dispatch)` for reducer-based state management.
`use_effect`	Schedule a side effect to run after the native commit.
`use_memo`	Return a memoized value that is recomputed only when `deps` change.
`use_callback`	Return a stable reference to `callback`, refreshed when `deps` change.
`use_ref`	Return a mutable ref dict `{"current": initial}` that persists across renders.
`create_context`	Create a new context with an optional default value.
`use_context`	Read the current value of `context` from the nearest `Provider`.
`Provider`	Provide `value` for `context` to all descendants of `child`.
`use_navigation`	Return a `NavigationHandle` for the screen.
`component`	Mark a function as a PythonNative component.

HookState ¶

HookState()

Per-instance storage for one component's hooks.

Each @component instance owns one HookState. Hooks are matched to slots by call order, so they must always be called in the same order across renders. Effects scheduled during render are deferred into _pending_effects and flushed after the reconciler commits native mutations, which guarantees effect callbacks can safely interact with the committed native tree.

Attributes:

Name	Type	Description
`states`	`List[Any]`	One entry per `use_state` / `use_reducer` call.
`effects`	`List[Tuple[Any, Any]]`	One `(deps, cleanup)` tuple per `use_effect` call.
`memos`	`List[Tuple[Any, Any]]`	One `(deps, value)` tuple per `use_memo` / `use_callback`.
`refs`	`List[dict]`	One mutable dict per `use_ref` call.
`hook_index`	`int`	Cursor reset to 0 at the start of every render.

Methods:

Name	Description
`reset_index`	Reset the hook cursor to the start of the slot list.
`flush_pending_effects`	Run effects queued during render, after native commit.
`cleanup_all_effects`	Run every outstanding cleanup function, then clear state.

reset_index ¶

reset_index() -> None

Reset the hook cursor to the start of the slot list.

Called by the reconciler at the beginning of every render pass.

flush_pending_effects ¶

flush_pending_effects() -> None

Run effects queued during render, after native commit.

For each pending effect, the previous cleanup is invoked first (if any), then the new effect callback. The new return value becomes the next cleanup.

cleanup_all_effects ¶

cleanup_all_effects() -> None

Run every outstanding cleanup function, then clear state.

Called when the component instance is unmounted by the reconciler.

Context ¶

Context(default: Any = None)

Container for a value shared across a subtree.

Created by create_context; consumed via use_context. Use Provider to set the value for a subtree.

Attributes:

Name	Type	Description
`default`		The value returned when no `Provider` ancestor exists.

NavigationHandle ¶

NavigationHandle(host: Any)

Handle returned by use_navigation.

Wraps the host's push/pop primitives so screens can navigate without knowing the underlying native navigation stack.

Example

import pythonnative as pn

@pn.component
def HomeScreen():
    nav = pn.use_navigation()
    return pn.Button(
        "Open Detail",
        on_click=lambda: nav.navigate(DetailScreen, params={"id": 42}),
    )

Methods:

Name	Description
`navigate`	Push `page` onto the navigation stack.
`go_back`	Pop the current screen and return to the previous one.
`get_params`	Return the params dict passed to this screen.

navigate ¶

navigate(page: Any, params: Optional[Dict[str, Any]] = None) -> None

Push page onto the navigation stack.

Parameters:

Name	Type	Description	Default
`page`	`Any`	Either a `@component` function or a dotted Python path (e.g., `"app.detail.DetailScreen"`).	required
`params`	`Optional[Dict[str, Any]]`	Optional dict of arguments serialized into the target screen.	`None`

go_back ¶

go_back() -> None

Pop the current screen and return to the previous one.

get_params ¶

get_params() -> Dict[str, Any]

Return the params dict passed to this screen.

Returns:

Type	Description
`Dict[str, Any]`	The dict supplied by the caller's
`Dict[str, Any]`	`navigate`
`Dict[str, Any]`	call, or an empty dict if none was supplied.

batch_updates ¶

batch_updates() -> Generator[None, None, None]

Coalesce multiple state updates into a single re-render.

State setters called inside the with block defer their re-render trigger until the block exits, so any number of set_* calls produce at most one render pass.

Yields:

Type	Description
`None`	None. The block executes normally; deferred renders fire on
`None`	exit.

Example

import pythonnative as pn

with pn.batch_updates():
    set_count(1)
    set_name("hello")

use_state ¶

use_state(initial: Any = None) -> Tuple[Any, Callable]

Return (value, setter) for component-local state.

State persists across re-renders of the same component instance. The setter accepts a value or a current -> new callable; calling it with an unchanged value is a no-op (no re-render).

Parameters:

Name	Type	Description	Default
`initial`	`Any`	Initial state value. If callable, it is invoked once on the first render (lazy initialization).	`None`

Returns:

Type	Description
`Any`	A 2-tuple `(value, setter)` where `value` is the current
`Callable`	state and `setter` updates it (and triggers a re-render).

Raises:

Type	Description
`RuntimeError`	If called outside a `@component` function.

Example

import pythonnative as pn

@pn.component
def Counter():
    count, set_count = pn.use_state(0)
    return pn.Button(
        f"Count: {count}",
        on_click=lambda: set_count(count + 1),
    )

use_reducer ¶

use_reducer(reducer: Callable[[Any, Any], Any], initial_state: Any) -> Tuple[Any, Callable]

Return (state, dispatch) for reducer-based state management.

A reducer is a pure function that takes the current state and an action and returns the next state. Use it instead of use_state when state transitions are complex enough that centralizing them in one function aids readability and testing.

Parameters:

Name	Type	Description	Default
`reducer`	`Callable[[Any, Any], Any]`	`reducer(current_state, action) -> new_state`. The component re-renders only when `reducer` returns a value different from the current state.	required
`initial_state`	`Any`	Initial state value, or a callable invoked once on the first render.	required

Returns:

Type	Description
`Any`	A 2-tuple `(state, dispatch)` where `dispatch` runs the
`Callable`	reducer with the supplied action.

Raises:

Type	Description
`RuntimeError`	If called outside a `@component` function.

Example

import pythonnative as pn

def reducer(state, action):
    if action == "increment":
        return state + 1
    if action == "reset":
        return 0
    return state

@pn.component
def Counter():
    count, dispatch = pn.use_reducer(reducer, 0)
    return pn.Row(
        pn.Button("+", on_click=lambda: dispatch("increment")),
        pn.Button("Reset", on_click=lambda: dispatch("reset")),
    )

use_effect ¶

use_effect(effect: Callable, deps: Optional[list] = None) -> None

Schedule a side effect to run after the native commit.

Effects are queued during the render pass and flushed once the reconciler has finished applying all native-view mutations, which means effect callbacks can safely measure layout or interact with committed native views.

The deps argument controls when the effect re-runs:

None: every render.
[]: mount only.
[a, b]: when a or b change (compared by identity, then ==).

effect may return a cleanup callable; the previous cleanup runs before the next effect (and on unmount).

Parameters:

Name	Type	Description	Default
`effect`	`Callable`	A zero-arg callable invoked after commit. Optionally returns a cleanup callable.	required
`deps`	`Optional[list]`	Dependency list, or `None` to run on every render.	`None`

Raises:

Type	Description
`RuntimeError`	If called outside a `@component` function.

Example

import pythonnative as pn

@pn.component
def Timer():
    seconds, set_seconds = pn.use_state(0)

    def tick():
        import threading
        t = threading.Timer(1.0, lambda: set_seconds(seconds + 1))
        t.start()
        return t.cancel

    pn.use_effect(tick, [seconds])
    return pn.Text(f"Elapsed: {seconds}s")

use_memo ¶

use_memo(factory: Callable[[], T], deps: list) -> T

Return a memoized value that is recomputed only when deps change.

Use this for expensive computations whose inputs change rarely. For cheap computations, plain inline code is faster (memoization itself has overhead).

Parameters:

Name	Type	Description	Default
`factory`	`Callable[[], T]`	Zero-arg callable returning the value.	required
`deps`	`list`	Dependency list. The value is recomputed when any element differs from the previous render.	required

Returns:

Type	Description
`T`	The cached or freshly computed value.

Raises:

Type	Description
`RuntimeError`	If called outside a `@component` function.

use_callback ¶

use_callback(callback: Callable, deps: list) -> Callable

Return a stable reference to callback, refreshed when deps change.

Equivalent to use_memo(lambda: callback, deps). Useful when passing a function as a prop to a memoized child component, so the child doesn't see a fresh function identity on every render.

Parameters:

Name	Type	Description	Default
`callback`	`Callable`	The callable to memoize.	required
`deps`	`list`	Dependency list controlling when the reference refreshes.	required

Returns:

Type	Description
`Callable`	A callable with stable identity across renders (until `deps` change).

use_ref ¶

use_ref(initial: Any = None) -> dict

Return a mutable ref dict {"current": initial} that persists across renders.

Refs are useful for storing values that must survive renders without triggering them: timers, last-seen values, native handles, and so on.

Parameters:

Name	Type	Description	Default
`initial`	`Any`	Value placed at `ref["current"]` on first render.	`None`

Returns:

Type	Description
`dict`	A dict with a single `"current"` key. Mutations to the dict do
`dict`	not trigger re-renders.

Raises:

Type	Description
`RuntimeError`	If called outside a `@component` function.

create_context ¶

create_context(default: Any = None) -> Context

Create a new context with an optional default value.

Parameters:

Name	Type	Description	Default
`default`	`Any`	Returned by `use_context` when there is no enclosing `Provider`.	`None`

Returns:

Type	Description
`Context`	A fresh `Context` instance.

Example

import pythonnative as pn

ThemeContext = pn.create_context({"primary": "#007AFF"})

use_context ¶

use_context(context: Context) -> Any

Read the current value of context from the nearest Provider.

If no enclosing Provider exists, returns the context's default.

Parameters:

Name	Type	Description	Default
`context`	`Context`	The `Context` to read from.	required

Returns:

Type	Description
`Any`	The current value for `context`.

Raises:

Type	Description
`RuntimeError`	If called outside a `@component` function.

Provider ¶

Provider(context: Context, value: Any, child: Element) -> Element

Provide value for context to all descendants of child.

Parameters:

Name	Type	Description	Default
`context`	`Context`	The `Context` to set.	required
`value`	`Any`	Value made available to descendants via `use_context`.	required
`child`	`Element`	Subtree under which the provider applies.	required

Returns:

Type	Description
`Element`	An `Element` that the reconciler treats
`Element`	as a context boundary.

Example

import pythonnative as pn

ThemeContext = pn.create_context({"primary": "#007AFF"})

@pn.component
def App():
    return pn.Provider(ThemeContext, {"primary": "#FF0000"}, MyView())

use_navigation ¶

use_navigation() -> NavigationHandle

Return a NavigationHandle for the screen.

Returns:

Type	Description
`NavigationHandle`	The handle bound to the current screen's host.

Raises:

Type	Description
`RuntimeError`	If called outside a component rendered via `create_page`.

component ¶

component(func: Callable) -> Callable[..., Element]

Mark a function as a PythonNative component.

The decorated function may use hooks (use_state, use_effect, etc.) and returns an Element tree. Each call site creates an independent component instance with its own hook state.

Positional arguments are mapped onto the function's positional parameters. If the function declares *args, positional arguments instead become the special children prop.

Parameters:

Name	Type	Description	Default
`func`	`Callable`	The function to wrap.	required

Returns:

Type	Description
`Callable[..., Element]`	A wrapper that, when called, returns an `Element` whose `type`
`Callable[..., Element]`	is `func` itself.

Example

import pythonnative as pn

@pn.component
def Greeting(name: str = "World"):
    return pn.Text(f"Hello, {name}!")

Next steps¶

Compose hooks into a screen: Components.
Run side effects from use_effect (after commit) and use_focus_effect (after focus).
Share state across the tree with create_context and Provider.