- `cli` – CLI tool and `pn` command (`src/pythonnative/cli/`)

- `components` – declarative element-creating functions (`components.py`)

- `element` – Element descriptor class (`element.py`)

- `events` – tag-based event routing between native views and Python callbacks (`events.py`)

- `gestures` – gesture descriptors and the pure-Python recognition arbiter (`gestures.py`)

- `hooks` – function components and hooks (`hooks.py`)

- `hot_reload` – file watcher and module reloader (`hot_reload.py`)

- `layout` – pure-Python flexbox engine (`layout.py`)

- `mutations` – batched mutation ops between reconciler and native backends (`mutations.py`)

- `native_modules` – native API modules for device capabilities (`native_modules/`)

- `native_views` – platform-specific native view creation and updates (`native_views/`)

- `navigation` – navigation containers and stack/tab/drawer navigators (`navigation.py`)

- **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect`, and navigation with `use_navigation`, all through one consistent pattern.

- **Typed `style` prop:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`.

- **Cross-platform flexbox engine:** A pure-Python, Yoga-style layout engine computes frames once and applies them to native views, so `flex`, `padding`, `aspect_ratio`, and `position: "absolute"` produce the same geometry on Android and iOS.

- **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation. Each commit lands as **one batched transaction** of mutation ops, and event callbacks are routed through a tag-based registry so re-renders that only change closures cost zero native calls. State updates re-render **locally** — only the component whose state changed (and its subtree) re-runs, and unchanged leaves reuse cached intrinsic measurements — so deep UIs stay responsive instead of re-rendering the whole app from the root on every tap.

- **Native-driven animations:** The `Animated` API (timing / spring / decay, awaitable or fire-and-forget) hands animations to Core Animation and `ViewPropertyAnimator` whenever possible, so no Python code runs per frame; a pure-Python ticker covers the rest.

- **Native gesture system:** Attach `Tap`, `LongPress`, `Pan`, `Swipe`, `Pinch`, and `Rotation` recognizers to any view via the `gestures=` prop — backed by `UIGestureRecognizer` on iOS and a unit-testable pure-Python arbiter on Android and desktop.

- **Virtualized lists:** `FlatList` / `SectionList` window their rows in Python over the platform scroll view — uniform, exact, or measured variable heights, grids, headers/footers, infinite scroll, and an imperative scroll controller, identical on every platform.

- **Direct native bindings:** Python calls platform APIs directly through Chaquopy and rubicon-objc, with no JavaScript bridge.

- **Custom-component SDK:** Wrap any platform widget as a first-class element with type-checked props via `pythonnative.sdk` (`Props`, `@native_component`, `element_factory`). Plugins distributed on PyPI auto-register through the `pythonnative.handlers` entry-point group.

- **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.

Native-backed gesture recognition, attached to any view-like element

via the `gestures=` prop. Descriptors are frozen dataclasses; their

numeric configuration crosses the bridge while callbacks are routed

through the tag-based event channel. See the

[Gestures guide](../guides/gestures.md) for usage patterns.

::: pythonnative.gestures

options:

show_root_heading: false

show_root_toc_entry: false

members_order: source

filters: ["!^_"]

show_if_no_docstring: true

- The [Gestures guide](../guides/gestures.md) walks through taps,

drags, and gesture-driven animations.

- [Animated](animated.md) pairs with `Pan` velocity for springs and

decays.

The bridge between PythonNative's element tree and concrete native

widgets. Each commit's diff is expressed as a flat list of mutation

ops referencing integer tags, applied through a single

call. Every element type maps to a

implementation in the

[`NativeViewRegistry`][pythonnative.native_views.NativeViewRegistry];

members_order: source

filters: ["!^_"]

::: pythonnative.mutations

options:

show_root_heading: false

show_root_toc_entry: false

members_order: source

filters: ["!^_"]

::: pythonnative.events

options:

show_root_heading: false

show_root_toc_entry: false

members_order: source

filters: ["!^_"]

::: pythonnative.native_views.base

3. **Reconciler.** On first render, the

[`Reconciler`][pythonnative.reconciler.Reconciler] walks the tree

and creates real native views via the platform backend. On

subsequent renders it diffs against the previous tree and emits the

minimal list of mutation ops (create / update / insert / remove /

destroy / set-frame), applied as **one batched transaction** per

commit through

[`apply_mutations`][pythonnative.native_views.NativeViewRegistry.apply_mutations].

State-driven renders are

**local**: a setter marks only its own component subtree dirty, and

[`flush_dirty`][pythonnative.reconciler.Reconciler.flush_dirty]

re-runs just those components instead of the whole app from the

so [`use_context`][pythonnative.use_context] still resolves. Hooks

record state reads, queue effects, and register memos. No native

mutations happen yet.

3. **Commit phase**: the reconciler turns the diff for each

re-rendered subtree into mutation ops referencing view tags, and

flushes them all in a single `apply_mutations` transaction. Event

callbacks are routed to the Python-side

[`EventRegistry`][pythonnative.events.EventRegistry] instead of

crossing the bridge, so callback-identity churn costs nothing.

4. **Layout phase**: a layout pass recomputes frames and emits

`SetFrameOp`s only for frames that changed. Leaves whose

`Element` is unchanged reuse a cached intrinsic measurement, so

untouched subtrees skip native `measure_intrinsic` calls.

5. **Effect phase**: pending effects are flushed in depth-first order

`"Button"`) to platform-native widget creation, property updates, and

child management. The

owns the tag-to-view table, applies each commit's mutation list, and

lazily imports only the relevant platform module at runtime, so the

package can be imported on any platform for testing.

Native events flow back through a single channel: handlers wire their

platform listeners once at view creation and call

[`dispatch_event`][pythonnative.events.dispatch_event] with the view's

tag; the [`EventRegistry`][pythonnative.events.EventRegistry] resolves

the current Python callback. Gestures

([`pythonnative.gestures`](../api/gestures.md)) and natively-driven

animations (the `Animated` API) ride the same tag infrastructure.

!!! note "Versus React Native"

**Lists:**

- [`FlatList(data, render_item, key_extractor, item_height, ...)`][pythonnative.FlatList]:

virtualized scrollable data list. Rows are mounted lazily as they

scroll into view; pass `item_height=` (or `get_item_height=`) for

exact extents, or let rows be measured on screen.

- [`SectionList(sections, render_item, render_section_header, item_height, ...)`][pythonnative.SectionList]:

virtualized list with section headers.