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 the Stack navigator pushes real native screen containers (UIViewController on iOS, Fragment on Android) so users get system-grade transitions and swipe-back gestures for free.

Three navigator factories are provided out of the box:

create_stack_navigator: push and pop screens with native transitions when the navigator is mounted at the root of an app host.
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.

Stack navigators rendered as the root of an app host (i.e. the parent use_navigation handle is the host's own handle) talk to the platform via that host's _push / _pop methods, so the back stack matches what UIKit / AndroidX maintain. Nested stacks (e.g. a stack inside a tab) fall back to in-Python state — there is no second native navigation controller to push onto in that case.

Example

import pythonnative as pn

Stack = pn.create_stack_navigator()

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

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.