Skip to content

Screen

The screen 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_screen and never need to be edited by app code.

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

Users do not write screen classes by hand. Instead they write @component functions and the native template calls create_screen to obtain a host that manages the reconciler and lifecycle for that screen.

The screen 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 named App:

import pythonnative as pn

@pn.component
def App():
    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.screen.create_screen(
    "app.main",
    native_instance,
)
host.on_create()

Functions:

Name Description
drain_ios_scheduled_renders

Entry point used by the iOS template to drain pending renders.
forward_lifecycle

Forward a Swift UIViewController lifecycle event to its host.
create_screen

Create a screen host for a function component.

drain_ios_scheduled_renders 

drain_ios_scheduled_renders() -> None

Entry point used by the iOS template to drain pending renders.

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_screen 

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

Create a screen host for a function component.

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

Parameters:

Name Type Description Default
component_path str

Either a module path like "app.main" (the module's top-level App attribute is used) or a dotted attribute path like "app.main.RootScreen". 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 screen.

 None
args_json Optional[str]

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

 None

Returns:

Type Description
_ScreenHost

A _ScreenHost ready to receive lifecycle callbacks (on_create,
_ScreenHost

on_pause, etc.) from the platform.
Example 
host = pythonnative.screen.create_screen(
    "app.main",
    native_instance,
    args_json='{"id": 42}',
)
host.on_create()

Next steps