Components¶

Element factory functions for the built-in PythonNative widgets. These return immutable Element descriptors; nothing is mounted to a native view tree until the Reconciler processes them.

For the visual and layout properties accepted by each component's style argument, see the Component Property Reference.

Built-in element factories for declarative UI composition.

Each function in this module returns an Element describing a native UI widget. Element factories are pure data: no native views are created until the reconciler mounts the element tree.

All visual and layout properties are passed via the style parameter, which accepts a dict or a list of dicts (later entries override earlier ones; see resolve_style).

Layout properties supported by every component:

width, height, flex, flex_grow, flex_shrink, margin, min_width, max_width, min_height, max_height, align_self.

Flex container properties (View / Column / Row):

flex_direction, justify_content, align_items, overflow, spacing, padding.

View is the universal flex container (like React Native's View). It defaults to flex_direction: "column". Column and Row are convenience wrappers that fix the direction.

Example

import pythonnative as pn

pn.Column(
    pn.Text("Hello", style={"font_size": 18}),
    pn.Button("Tap", on_click=lambda: print("tapped")),
    style={"spacing": 12, "padding": 16},
)

Functions:

Name	Description
`Text`	Display a string of text.
`Button`	Display a tappable button.
`TextInput`	Display a single-line text entry field.
`Image`	Display an image from a resource path or URL.
`Switch`	Display a toggle switch.
`ProgressBar`	Show determinate progress as a value between 0.0 and 1.0.
`ActivityIndicator`	Show an indeterminate loading spinner.
`WebView`	Embed web content from a URL.
`Spacer`	Insert empty space inside a flex container.
`Slider`	Continuous-value slider between `min_value` and `max_value`.
`View`	Universal flex container (like React Native's `View`).
`Column`	Arrange children vertically.
`Row`	Arrange children horizontally.
`ScrollView`	Wrap a single child in a scrollable container.
`SafeAreaView`	Container that respects safe-area insets (notch, status bar, home indicator).
`Modal`	Overlay modal dialog.
`Pressable`	Wrap any child element with tap and long-press handlers.
`ErrorBoundary`	Catch render errors in `child` and display `fallback` instead.
`FlatList`	Scrollable list that renders items from `data` using `render_item`.

Text ¶

Text(text: str = '', *, style: StyleValue = None, key: Optional[str] = None) -> Element

Display a string of text.

Style properties: font_size, color, bold, text_align, background_color, max_lines, plus the common layout props.

Parameters:

Name	Type	Description	Default
`text`	`str`	Text content to display.	`''`
`style`	`StyleValue`	Style dict (or list of dicts) controlling appearance and layout.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation in lists.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Text"`.

Button ¶

Button(title: str = '', *, on_click: Optional[Callable[[], None]] = None, enabled: bool = True, style: StyleValue = None, key: Optional[str] = None) -> Element

Display a tappable button.

Style properties: color, background_color, font_size, plus the common layout props.

Parameters:

Name	Type	Description	Default
`title`	`str`	Button label.	`''`
`on_click`	`Optional[Callable[[], None]]`	Callback invoked when the user taps the button.	`None`
`enabled`	`bool`	When `False`, the button is disabled and cannot be tapped.	`True`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Button"`.

TextInput ¶

TextInput(*, value: str = '', placeholder: str = '', on_change: Optional[Callable[[str], None]] = None, secure: bool = False, style: StyleValue = None, key: Optional[str] = None) -> Element

Display a single-line text entry field.

Style properties: font_size, color, background_color, plus the common layout props.

Parameters:

Name	Type	Description	Default
`value`	`str`	Current text content (controlled-input pattern).	`''`
`placeholder`	`str`	Hint shown when `value` is empty.	`''`
`on_change`	`Optional[Callable[[str], None]]`	Callback invoked with the new string each keystroke.	`None`
`secure`	`bool`	When `True`, characters are masked (use for passwords).	`False`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"TextInput"`.

Image ¶

Image(source: str = '', *, scale_type: Optional[str] = None, style: StyleValue = None, key: Optional[str] = None) -> Element

Display an image from a resource path or URL.

Style properties: background_color, plus the common layout props.

Parameters:

Name	Type	Description	Default
`source`	`str`	Image resource name or URL.	`''`
`scale_type`	`Optional[str]`	Platform-specific fit mode (e.g., `"fit"`, `"fill"`, `"center"`).	`None`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Image"`.

Switch ¶

Switch(*, value: bool = False, on_change: Optional[Callable[[bool], None]] = None, style: StyleValue = None, key: Optional[str] = None) -> Element

Display a toggle switch.

Parameters:

Name	Type	Description	Default
`value`	`bool`	Current on/off state.	`False`
`on_change`	`Optional[Callable[[bool], None]]`	Callback invoked with the new boolean state.	`None`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Switch"`.

ProgressBar ¶

ProgressBar(*, value: float = 0.0, style: StyleValue = None, key: Optional[str] = None) -> Element

Show determinate progress as a value between 0.0 and 1.0.

For indeterminate progress, use ActivityIndicator instead.

Parameters:

Name	Type	Description	Default
`value`	`float`	Fraction complete (clamped to `[0.0, 1.0]` by the platform handler).	`0.0`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"ProgressBar"`.

ActivityIndicator ¶

ActivityIndicator(*, animating: bool = True, style: StyleValue = None, key: Optional[str] = None) -> Element

Show an indeterminate loading spinner.

Parameters:

Name	Type	Description	Default
`animating`	`bool`	When `False`, the spinner is hidden.	`True`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type
`Element`	`"ActivityIndicator"`.

WebView ¶

WebView(*, url: str = '', style: StyleValue = None, key: Optional[str] = None) -> Element

Embed web content from a URL.

Parameters:

Name	Type	Description	Default
`url`	`str`	HTTP(S) URL to load.	`''`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"WebView"`.

Spacer ¶

Spacer(*, size: Optional[float] = None, flex: Optional[float] = None, key: Optional[str] = None) -> Element

Insert empty space inside a flex container.

Pass size for a fixed gap, or flex to expand and absorb remaining space.

Parameters:

Name	Type	Description	Default
`size`	`Optional[float]`	Fixed gap in dp/pt along the parent's main axis.	`None`
`flex`	`Optional[float]`	Flex-grow weight; useful for pushing siblings to the opposite end of a `Row` or `Column`.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Spacer"`.

Slider ¶

Slider(*, value: float = 0.0, min_value: float = 0.0, max_value: float = 1.0, on_change: Optional[Callable[[float], None]] = None, style: StyleValue = None, key: Optional[str] = None) -> Element

Continuous-value slider between min_value and max_value.

Parameters:

Name	Type	Description	Default
`value`	`float`	Current slider value.	`0.0`
`min_value`	`float`	Lower bound.	`0.0`
`max_value`	`float`	Upper bound.	`1.0`
`on_change`	`Optional[Callable[[float], None]]`	Callback invoked with the new value as the user drags.	`None`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Slider"`.

View ¶

View(*children: Element, style: StyleValue = None, key: Optional[str] = None) -> Element

Universal flex container (like React Native's View).

Defaults to flex_direction: "column". Override via style:

pn.View(child_a, child_b, style={"flex_direction": "row"})

Flex container properties (inside style):

flex_direction: "column" (default), "row", "column_reverse", "row_reverse".
justify_content: main-axis distribution. Accepts "flex_start" (default), "center", "flex_end", "space_between", "space_around", "space_evenly".
align_items: cross-axis alignment. Accepts "stretch" (default), "flex_start", "center", "flex_end".
overflow: "visible" (default) or "hidden".
spacing, padding, background_color.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Child elements rendered inside the container.	`()`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"View"`.

Column ¶

Column(*children: Element, style: StyleValue = None, key: Optional[str] = None) -> Element

Arrange children vertically.

Convenience wrapper around View with flex_direction fixed to "column". Use View directly if you need to switch between row and column at runtime.

Style properties: spacing, padding, align_items, justify_content, background_color, overflow, plus the common layout props.

align_items controls cross-axis (horizontal) alignment: "stretch" (default), "flex_start" / "leading", "center", or "flex_end" / "trailing".

justify_content controls main-axis (vertical) distribution: "flex_start" (default), "center", "flex_end", "space_between", "space_around", "space_evenly".

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Child elements stacked top to bottom.	`()`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Column"`.

Row ¶

Row(*children: Element, style: StyleValue = None, key: Optional[str] = None) -> Element

Arrange children horizontally.

Convenience wrapper around View with flex_direction fixed to "row". Use View directly if you need to switch between row and column at runtime.

Style properties: spacing, padding, align_items, justify_content, background_color, overflow, plus the common layout props.

align_items controls cross-axis (vertical) alignment: "stretch" (default), "flex_start" / "top", "center", or "flex_end" / "bottom".

justify_content controls main-axis (horizontal) distribution: "flex_start" (default), "center", "flex_end", "space_between", "space_around", "space_evenly".

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Child elements arranged left to right.	`()`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Row"`.

ScrollView ¶

ScrollView(child: Optional[Element] = None, *, style: StyleValue = None, key: Optional[str] = None) -> Element

Wrap a single child in a scrollable container.

Parameters:

Name	Type	Description	Default
`child`	`Optional[Element]`	The single child to scroll. Wrap multiple elements in a `Column` or `Row` first.	`None`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"ScrollView"`.

SafeAreaView ¶

SafeAreaView(*children: Element, style: StyleValue = None, key: Optional[str] = None) -> Element

Container that respects safe-area insets (notch, status bar, home indicator).

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Child elements that should avoid system UI overlays.	`()`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"SafeAreaView"`.

Modal ¶

Modal(*children: Element, visible: bool = False, on_dismiss: Optional[Callable[[], None]] = None, title: Optional[str] = None, style: StyleValue = None, key: Optional[str] = None) -> Element

Overlay modal dialog.

The modal is shown when visible=True and hidden when False. Drive visible from a hook so the parent component can dismiss the modal in response to user actions.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Modal content.	`()`
`visible`	`bool`	Controls whether the modal is presented.	`False`
`on_dismiss`	`Optional[Callable[[], None]]`	Callback invoked when the user dismisses the modal via system gesture (e.g., backdrop tap or back button).	`None`
`title`	`Optional[str]`	Optional title bar text.	`None`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Modal"`.

Pressable ¶

Pressable(child: Optional[Element] = None, *, on_press: Optional[Callable[[], None]] = None, on_long_press: Optional[Callable[[], None]] = None, key: Optional[str] = None) -> Element

Wrap any child element with tap and long-press handlers.

Useful for making non-button elements (text, images, custom views) respond to user taps without altering their visual appearance.

Parameters:

Name	Type	Description	Default
`child`	`Optional[Element]`	The single element to make pressable.	`None`
`on_press`	`Optional[Callable[[], None]]`	Callback invoked on a normal tap.	`None`
`on_long_press`	`Optional[Callable[[], None]]`	Callback invoked on a sustained press.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Pressable"`.

ErrorBoundary ¶

ErrorBoundary(child: Optional[Element] = None, *, fallback: Optional[Any] = None, key: Optional[str] = None) -> Element

Catch render errors in child and display fallback instead.

fallback may be an Element or a callable that receives the exception and returns an Element. Useful for isolating risky subtrees so a single failure doesn't crash the page.

Parameters:

Name	Type	Description	Default
`child`	`Optional[Element]`	Subtree to wrap.	`None`
`fallback`	`Optional[Any]`	Element to render when `child` raises during render, or a callable `fallback(err) -> Element`.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"__ErrorBoundary__"`.

Example

import pythonnative as pn

pn.ErrorBoundary(
    MyRiskyComponent(),
    fallback=lambda err: pn.Text(f"Error: {err}"),
)

FlatList ¶

FlatList(*, data: Optional[List[Any]] = None, render_item: Optional[Callable[[Any, int], Element]] = None, key_extractor: Optional[Callable[[Any, int], str]] = None, separator_height: float = 0, style: StyleValue = None, key: Optional[str] = None) -> Element

Scrollable list that renders items from data using render_item.

Each item is rendered by calling render_item(item, index). If key_extractor is provided, it is called as key_extractor(item, index) to produce a stable key for keyed reconciliation, which is essential for efficient updates when the list is reordered or partially mutated.

Parameters:

Name	Type	Description	Default
`data`	`Optional[List[Any]]`	Iterable of arbitrary item values.	`None`
`render_item`	`Optional[Callable[[Any, int], Element]]`	Function called per item, returning an `Element`. Defaults to wrapping each item in a `Text`.	`None`
`key_extractor`	`Optional[Callable[[Any, int], str]]`	Function returning a stable key per item.	`None`
`separator_height`	`float`	Vertical gap between items, in dp/pt.	`0`
`style`	`StyleValue`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation of the list itself.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"ScrollView"` (a
`Element`	column wrapped in a scroll container).

Example

import pythonnative as pn

items = [{"id": 1, "name": "Apples"}, {"id": 2, "name": "Oranges"}]

pn.FlatList(
    data=items,
    render_item=lambda item, _: pn.Text(item["name"]),
    key_extractor=lambda item, _: str(item["id"]),
    separator_height=4,
)

Next steps¶

Wire interactions with Hooks.
Compose styles with StyleSheet.
Build navigation with NavigationContainer.