- **Native-backed navigation:** Declarative `Stack`, `Tab`, and `Drawer` navigators inspired by React Navigation. The root stack drives the platform's native navigation controller (`UINavigationController` on iOS, AndroidX Navigation Component on Android), so transitions, back gestures, and the hardware back button match what users expect.

- **Fast Refresh hot reload:** `pn run --hot-reload` watches `app/` and patches edits into the running app on save, preserving component state across most changes.

def App():

change. The screen host is the only code that updates the underlying

Your app module defines a top-level component named `App`:

import pythonnative as pn

def App():

return pn.NavigationContainer(...)

The bundled Android `ScreenFragment` and iOS `ViewController` load

your app by **module path** (`"app.main"`) and look up the

module's top-level `App` attribute. There is no registration step

or imperative bootstrap call. If you need to expose a

differently-named root component, configure the templates to load

an explicit dotted path like `"app.main.RootScreen"` instead.

| Screen host | [Screen](screen.md) | [`create_screen`][pythonnative.create_screen] |

The screen host owns a [`Reconciler`][pythonnative.reconciler.Reconciler],

host via [`create_screen`][pythonnative.create_screen] and never need to

be edited by app code.

::: pythonnative.screen

- See how navigation hosts each screen in

[`create_screen`][pythonnative.create_screen] internally to bootstrap

10. **`App` entry point.** The user's app module (`app/main.py`)

defines a top-level component named `App`. Native templates

import that module by path (`"app.main"`) and look up its `App`

attribute, so users never write a separate registration step.

Components with other names can still be loaded by passing an

explicit dotted path like `"app.main.RootScreen"` to the

template.

The entry point [`create_screen`][pythonnative.create_screen] is called

[`create_screen`][pythonnative.create_screen] internally with the

- `ScreenFragment` calls [`create_screen`][pythonnative.create_screen]

near-instant UI updates without full rebuilds.

PythonNative uses a **Fast Refresh** strategy:

1. Reload the changed module(s) on the device.

2. For every active screen host, walk the VNode tree and collect every

component function defined in a reloaded module.

3. Match each one to its replacement by `__module__` +

`__qualname__` and rewrite `Element.type` in place.

4. Trigger one reconcile pass. Because the VNode and its `HookState`

are reused, component state (`use_state`, `use_reducer`, refs) is

preserved across the edit.

If Fast Refresh can't produce a clean swap, the host falls back to a

**full remount** of its root component. See

PythonNative navigation is **declarative** and **native-backed**:

- The user describes their app as a tree of navigators

([`create_stack_navigator`][pythonnative.create_stack_navigator],

[`create_tab_navigator`][pythonnative.create_tab_navigator],

[`create_drawer_navigator`][pythonnative.create_drawer_navigator])

wrapped in

[`NavigationContainer`][pythonnative.NavigationContainer], and

names the root component `App` so the native templates can find

it.

- The outermost `Stack.Navigator` delegates `navigate(...)`,

`go_back()`, and `reset(...)` to the platform's native navigation

controller — `UINavigationController` on iOS and the AndroidX

Navigation Component on Android. Nested navigators (tabs inside a

stack, stacks inside tabs) stay in Python and reuse the existing

reconciler.

- Each pushed native screen is a fresh host with its own reconciler

and `_ScreenHost`. Initial routes are forwarded via host arguments

(`__pn_initial_route__` / `__pn_initial_params__`), so a pushed

screen knows which `Stack.Screen` to render on its first frame.

- Inside any screen, [`use_navigation`][pythonnative.use_navigation]

returns a `NavigationHandle`; [`use_route`][pythonnative.use_route]

returns the current route name and params. Both are the same

hooks regardless of whether the active navigator is native-backed

or pure-Python.

See the [Navigation guide](../guides/navigation.md) for the full

walkthrough, including how `options={"title": ...}` flows into the

native navigation bar.

stack of generic `ScreenFragment`s driven by a navigation graph.

def App():

The entry point [`create_screen`][pythonnative.create_screen] is called

don't call it directly: name your top-level component `App` (so the

templates can find it by convention) and `pythonnative.json` points

at the module that defines it.

def App():

- Initial mount via [`create_screen`][pythonnative.create_screen].

immediately. The screen host caps the loop to prevent runaway

The screen host forwards the platform's app-level lifecycle to navigators

The `app/main.py` that `pn init` writes already returns a small

Save this as `app/main.py`:

def App():

- `@pn.component` registers `App` as a function component. Hooks

re-render scheduled by the screen host.