Navigation¶

The declarative navigation API: a single NavigationContainer holds one or more navigators (stack, tab, or drawer), and any descendant function component can navigate via use_navigation or read its current route with use_route.

Declarative navigation for PythonNative.

Provides a component-based navigation system inspired by React Navigation. Navigators manage screen state in Python and render the active screen's component through the standard reconciler pipeline, so hooks (use_state, use_effect, etc.) and providers continue to work inside navigated screens.

Three navigator factories are provided out of the box:

create_stack_navigator: push and pop screens.
create_tab_navigator: switch between sibling tabs (with a tab bar).
create_drawer_navigator: switch between sibling screens via a side drawer menu.

Navigators may be nested arbitrarily; nested handles forward unknown routes and root-level go_back calls to their parent.

Example

import pythonnative as pn
from pythonnative.navigation import NavigationContainer, create_stack_navigator

Stack = create_stack_navigator()

@pn.component
def App():
    return NavigationContainer(
        Stack.Navigator(
            Stack.Screen("Home", component=HomeScreen),
            Stack.Screen("Detail", component=DetailScreen),
        )
    )

Functions:

Name	Description
`create_stack_navigator`	Create a stack-based navigator.
`create_tab_navigator`	Create a tab-based navigator.
`create_drawer_navigator`	Create a drawer-based navigator.
`NavigationContainer`	Root container for the navigation tree.
`use_route`	Return the current route's params dict.
`use_focus_effect`	Run `effect` only while the screen is focused.

create_stack_navigator ¶

create_stack_navigator() -> Any

Create a stack-based navigator.

Stacks support push (navigate(name, params=...)) and pop (go_back()). The active screen is the top of the stack.

Returns:

Type	Description
`Any`	An object exposing two static factories:
`Any`	`Screen(name, *, component, options=None)`: define a screen.
`Any`	`Navigator(*screens, initial_route=None, key=None)`: render the navigator with the given screens.

Example

import pythonnative as pn
from pythonnative.navigation import (
    NavigationContainer, create_stack_navigator
)

Stack = create_stack_navigator()

@pn.component
def App():
    return NavigationContainer(
        Stack.Navigator(
            Stack.Screen("Home", component=HomeScreen),
            Stack.Screen("Detail", component=DetailScreen),
            initial_route="Home",
        )
    )

create_tab_navigator ¶

create_tab_navigator() -> Any

Create a tab-based navigator.

Tab navigators render a tab bar and switch between sibling screens. Use options={"title": "..."} on a Screen to label the tab.

Returns:

Type	Description
`Any`	An object exposing static `Screen(...)` and `Navigator(...)`
`Any`	factories analogous to
`Any`	`create_stack_navigator`.

Example

import pythonnative as pn
from pythonnative.navigation import (
    NavigationContainer, create_tab_navigator
)

Tab = create_tab_navigator()

@pn.component
def App():
    return NavigationContainer(
        Tab.Navigator(
            Tab.Screen("Home", component=HomeScreen, options={"title": "Home"}),
            Tab.Screen("Settings", component=SettingsScreen),
        )
    )

create_drawer_navigator ¶

create_drawer_navigator() -> Any

Create a drawer-based navigator.

Drawer navigators render a side panel for switching between sibling screens. The navigation handle returned by use_navigation inside a drawer navigator includes open_drawer(), close_drawer(), and toggle_drawer() methods in addition to the standard navigate/go_back/reset interface.

Returns:

Type	Description
`Any`	An object exposing static `Screen(...)` and `Navigator(...)`
`Any`	factories analogous to
`Any`	`create_stack_navigator`.

Example

import pythonnative as pn
from pythonnative.navigation import (
    NavigationContainer, create_drawer_navigator
)

Drawer = create_drawer_navigator()

@pn.component
def App():
    return NavigationContainer(
        Drawer.Navigator(
            Drawer.Screen("Home", component=HomeScreen, options={"title": "Home"}),
            Drawer.Screen("Settings", component=SettingsScreen),
        )
    )

NavigationContainer ¶

NavigationContainer(child: Element, *, key: Optional[str] = None) -> Element

Root container for the navigation tree.

Wraps the child navigator in a full-size view. All declarative navigators (stack, tab, drawer) should be nested inside a NavigationContainer.

Parameters:

Name	Type	Description	Default
`child`	`Element`	The root navigator element (typically a `Stack.Navigator`, `Tab.Navigator`, or `Drawer.Navigator`).	required
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"View"`.

Example

import pythonnative as pn
from pythonnative.navigation import (
    NavigationContainer, create_stack_navigator
)

Stack = create_stack_navigator()

@pn.component
def App():
    return NavigationContainer(
        Stack.Navigator(
            Stack.Screen("Home", component=HomeScreen),
        )
    )

use_route ¶

use_route() -> Dict[str, Any]

Return the current route's params dict.

Convenience hook that reads from the navigation context. Equivalent to use_navigation().get_params() but tolerates the no-navigation case (returns {} instead of raising).

Returns:

Type	Description
`Dict[str, Any]`	The current route's `params` dict, or `{}` if no navigator is
`Dict[str, Any]`	in scope.

Example

import pythonnative as pn

@pn.component
def DetailScreen():
    params = pn.use_route()
    item_id = params.get("id")
    return pn.Text(f"Item {item_id}")

use_focus_effect ¶

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

Run effect only while the screen is focused.

Like use_effect, but the callback runs only when the enclosing navigator marks this screen as the active one. Useful for starting subscriptions, refreshing data, or pausing animations on the inactive screen.

Parameters:

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

Example

import pythonnative as pn

@pn.component
def HomeScreen():
    pn.use_focus_effect(lambda: print("screen focused"), [])
    return pn.Text("Home")

Next steps¶

See worked examples in Navigation guide.
Inspect the imperative handle returned by use_navigation.