Skip to content

Page

The page host owns a Reconciler, schedules re-renders, and forwards platform lifecycle hooks (resume, pause, destroy) to navigators and effects. The bundled Android (MainActivity) and iOS (ViewController) templates create a host via create_page and never need to be edited by app code.

Page host: the bridge between native lifecycle and function components.

Users do not subclass Page. Instead they write @component functions and the native template calls create_page to obtain a host that manages the reconciler and lifecycle.

The page host owns:

  • A Reconciler backed by the platform's native-view registry.
  • A NavigationHandle (delivered to components via the navigation context) so screens can push and pop without holding a direct reference to native classes.
  • Render scheduling. State changes during render are queued and drained in batches so the reconciler runs at most a bounded number of passes per user gesture.
Example

User code defines a top-level component:

import pythonnative as pn

@pn.component
def MainPage():
    count, set_count = pn.use_state(0)
    return pn.Column(
        pn.Text(f"Count: {count}", style={"font_size": 24}),
        pn.Button("Tap me", on_click=lambda: set_count(count + 1)),
        style={"spacing": 12, "padding": 16},
    )

The native template wires it in:

host = pythonnative.page.create_page(
    "app.main_page.MainPage",
    native_instance,
)
host.on_create()

Functions:

Name Description
forward_lifecycle

Forward a Swift UIViewController lifecycle event to its host.
create_page

Create a page host for a function component.

forward_lifecycle 

forward_lifecycle(native_addr: int, event: str) -> None

Forward a Swift UIViewController lifecycle event to its host.

Parameters:

Name Type Description Default
native_addr int

Pointer (int) of the calling UIViewController instance, used to look up the registered host.

 required
event str

Lifecycle method name (e.g., "on_resume").

 required

create_page 

create_page(component_path: str, native_instance: Any = None, args_json: Optional[str] = None) -> _AppHost

Create a page host for a function component.

Called by native templates (PageFragment.kt on Android, ViewController.swift on iOS) to bridge the native lifecycle to a @component function.

Parameters:

Name Type Description Default
component_path str

Dotted Python path to the component, e.g., "app.main_page.MainPage". The function is imported lazily so user modules can be reloaded by the dev server.

 required
native_instance Any

The native Activity (Android) or UIViewController (iOS) pointer that owns this page.

 None
args_json Optional[str]

Optional JSON string of navigation arguments to pass to the component on first render.

 None

Returns:

Type Description
_AppHost

An _AppHost ready to receive lifecycle callbacks (on_create,
_AppHost

on_pause, etc.) from the platform.
Example 
host = pythonnative.page.create_page(
    "app.main_page.MainPage",
    native_instance,
    args_json='{"id": 42}',
)
host.on_create()

Next steps