1. **Declarative element tree:** Your `@pn.component` function returns a tree of `Element` descriptors (similar to React elements / virtual DOM nodes).

2. **Function components and hooks:** All UI is built with `@pn.component` functions using `use_state`, `use_reducer`, `use_effect`, `use_navigation`, etc. — inspired by React hooks but designed for Python.

3. **Reconciler:** On first render, the reconciler walks the tree and creates real native views via the platform backend. On subsequent renders (triggered by hook state changes), it diffs the new tree against the old one and applies the minimal set of native mutations.

4. **Post-render effects:** Effects queued via `use_effect` are flushed **after** the reconciler commits native mutations, matching React semantics. This guarantees that effect callbacks interact with the committed native tree.

5. **State batching:** Multiple state updates triggered during a render pass (e.g. from effects) are automatically batched into a single re-render. Explicit batching is available via `pn.batch_updates()`.

6. **Key-based reconciliation:** Children can be assigned stable `key` values to preserve identity across re-renders — critical for lists and dynamic content.

7. **Error boundaries:** `pn.ErrorBoundary` catches render errors in child subtrees and displays fallback UI, preventing a single component failure from crashing the entire page.

8. **Direct bindings:** Under the hood, native views are created and updated through direct platform calls:

- **iOS:** rubicon-objc exposes Objective-C/Swift classes (`UILabel`, `UIButton`, `UIStackView`, etc.).

- **Android:** Chaquopy exposes Java classes (`android.widget.TextView`, `android.widget.Button`, etc.) via the JNI bridge.

9. **Thin native bootstrap:** The host app remains native (Android `Activity` or iOS `UIViewController`). It calls `create_page()` internally to bootstrap your Python component, and the reconciler drives the UI from there.

The reconciler uses **key-based diffing** (matching children by key first, then by position). When a child with the same key/type is found, its props are updated in-place on the native view. When the type changes, the old native view is destroyed and a new one is created.

1. **Render phase:** Component functions execute. Hooks record state reads, queue effects, and register memos. No native mutations happen yet.

2. **Commit phase:** The reconciler applies the diff to native views — creating, updating, and removing views as needed.

3. **Effect phase:** Pending effects are flushed in depth-first order (children before parents). Cleanup functions from the previous render run before new effect callbacks.

4. **Drain phase:** If effects set state, a new render pass is automatically triggered and the cycle repeats (up to a safety limit to prevent infinite loops).

PythonNative uses a single component model: **function components** decorated with `@pn.component`.

Each component is a Python function that:

- Accepts props as keyword arguments

- Uses hooks for state (`use_state`, `use_reducer`), side effects (`use_effect`), navigation (`use_navigation`), and more

- Returns an `Element` tree describing the UI

- Each call site creates an independent instance with its own hook state

- `Modal(*children, visible, on_dismiss, title)` — modal dialog

**Error handling:**

- `ErrorBoundary(child, fallback)` — catches render errors in child and displays fallback

**Lists:**

- `FlatList(data, render_item, key_extractor, separator_height)` — scrollable data list

- `use_state(initial)` — local component state; returns `(value, setter)`

- `use_reducer(reducer, initial_state)` — reducer-based state; returns `(state, dispatch)`

- `use_effect(effect, deps)` — side effects, run after native commit (timers, API calls, subscriptions)

- `use_memo(factory, deps)` — memoised computed values

- `use_callback(fn, deps)` — stable function references

- `use_ref(initial)` — mutable ref that persists across renders

count, set_count = pn.use_state(lambda: compute_default())

For complex state logic, `use_reducer` lets you manage state transitions through a reducer function — similar to React's `useReducer`:

def reducer(state, action):

if action == "increment":

return state + 1

if action == "decrement":

return state - 1

if action == "reset":

return 0

return state

def Counter():

count, dispatch = pn.use_reducer(reducer, 0)

return pn.Column(

pn.Text(f"Count: {count}"),

pn.Row(

pn.Button("-", on_click=lambda: dispatch("decrement")),

pn.Button("+", on_click=lambda: dispatch("increment")),

pn.Button("Reset", on_click=lambda: dispatch("reset")),

style={"spacing": 8},

),

)

The reducer receives the current state and an action, and returns the new state. Actions can be any value (strings, dicts, etc.). The component only re-renders when the reducer returns a different state.

Run side effects **after** the native view tree is committed. The effect function may return a cleanup callable.

return pn.Text(f"Elapsed: {seconds}s")

Effects are **deferred** — they are queued during the render phase and executed after the reconciler finishes committing native view mutations. This means effect callbacks can safely measure layout or interact with the committed native tree.

Dependency control:

- `pn.use_effect(fn, None)` — run on every render

return pn.Text(f"Welcome, {user['name']}")

By default, each state setter call triggers a re-render. When you need to update multiple pieces of state at once, use `pn.batch_updates()` to coalesce them into a single render pass:

def Form():

name, set_name = pn.use_state("")

email, set_email = pn.use_state("")

def on_submit():

with pn.batch_updates():

set_name("Alice")

set_email("alice@example.com")

# single re-render here

return pn.Column(

pn.Text(f"{name} <{email}>"),

pn.Button("Fill", on_click=on_submit),

)

State updates triggered by effects during a render pass are automatically batched — the framework drains any pending re-renders after effect flushing completes, so you don't need `batch_updates()` inside effects.

Wrap risky components in `pn.ErrorBoundary` to catch render errors and display a fallback UI:

def App():

return pn.ErrorBoundary(

MyRiskyComponent(),

fallback=lambda err: pn.Text(f"Something went wrong: {err}"),

)

Without an error boundary, an exception during rendering crashes the entire page. Error boundaries catch errors during both initial mount and subsequent reconciliation.

Extract reusable stateful logic into plain functions:

ActivityIndicator,

Button,

Column,

ErrorBoundary,

FlatList,

Image,

Modal,

from .element import Element

from .hooks import (

Provider,

batch_updates,

component,

create_context,

use_callback,

use_context,

use_effect,

use_memo,

use_navigation,

use_reducer,

use_ref,

use_state,

)

"ActivityIndicator",

"Button",

"Column",

"ErrorBoundary",

"FlatList",

"Image",

"Modal",

"Element",

"create_page",

# Hooks

"batch_updates",

"component",

"create_context",

"use_callback",

"use_context",

"use_effect",

"use_memo",

"use_navigation",

"use_reducer",

"use_ref",

"use_state",

"Provider",

return Element("Pressable", props, children, key=key)

def ErrorBoundary(

child: Optional[Element] = None,

*,

fallback: Optional[Any] = None,

key: Optional[str] = None,

) -> Element:

"""Catch render errors in *child* and display *fallback* instead.

props: Dict[str, Any] = {}

if fallback is not None:

props["__fallback__"] = fallback

children = [child] if child is not None else []

return Element("__ErrorBoundary__", props, children, key=key)

def FlatList(

*,

data: Optional[List[Any]] = None,