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.

Each factory function (Text, Button, …) is a fully-typed thin wrapper that builds an Element through the shared :func:_make_element helper, so style resolution, ref attachment, None-default dropping, and forced overrides (e.g. Column's fixed flex_direction) live in exactly one place. The factory signatures themselves are the canonical prop schemas: editors and type checkers validate calls directly against them.

Example

import pythonnative as pn

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

Classes:

Name	Description
`ListController`	Imperative scroll handle published on a list's `ref`.

Functions:

Name	Description
`Text`	Display a string of text, optionally with styled nested spans.
`Button`	Display a tappable button.
`TextInput`	Display a text-entry field (single-line by default, or `multiline`).
`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 or an inline HTML string.
`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 children in a scrollable container.
`SafeAreaView`	Container that respects safe-area insets (notch, status bar, home indicator).
`Modal`	Overlay modal dialog backed by a real native presentation.
`Pressable`	Wrap children with tap / long-press / gesture handlers.
`TouchableOpacity`	Wrap children so they fade to `active_opacity` while pressed.
`ImageBackground`	Render `children` layered on top of a background image.
`Checkbox`	A boolean checkbox with an optional inline label.
`SegmentedControl`	A horizontal multi-choice control (one selected segment at a time).
`DatePicker`	A native date / time picker.
`Fragment`	Group children without adding a wrapping native view.
`Portal`	Render `children` into a full-screen overlay above everything else.
`ErrorBoundary`	Catch render errors in the wrapped subtree and display `fallback` instead.
`FlatList`	Virtualized scrollable list that renders items from `data` lazily.
`SectionList`	Virtualized list with section headers interleaved between row groups.
`StatusBar`	Configure the device's status bar appearance.
`KeyboardAvoidingView`	Wrap content that should shift up when the keyboard is shown.
`RefreshControl`	Pull-to-refresh spec for `ScrollView` / `FlatList`.
`Picker`	A real native dropdown / select widget.

ListController ¶

ListController(scroll_to_offset: Callable[[float, bool], None], scroll_to_index: Callable[[int, bool], None], scroll_to_end: Callable[[bool], None])

Imperative scroll handle published on a list's ref.

FlatList and SectionList install a ListController on ref.current (via use_imperative_handle) after mount and clear it back to None on unmount.

Example

import pythonnative as pn

@pn.component
def Chat(messages):
    list_ref = pn.use_ref()
    pn.use_layout_effect(
        lambda: list_ref.current and list_ref.current.scroll_to_end(animated=False),
        [len(messages)],
    )
    return pn.FlatList(data=messages, render_item=Bubble, ref=list_ref)

Methods:

Name	Description
`scroll_to_offset`	Scroll to an absolute content offset in points.
`scroll_to_index`	Scroll so the row at `index` sits at the top of the viewport.
`scroll_to_end`	Scroll to the end of the content.

scroll_to_offset ¶

scroll_to_offset(offset: float, animated: bool = True) -> None

Scroll to an absolute content offset in points.

scroll_to_index ¶

scroll_to_index(index: int, animated: bool = True) -> None

Scroll so the row at index sits at the top of the viewport.

scroll_to_end ¶

scroll_to_end(animated: bool = True) -> None

Scroll to the end of the content.

Text ¶

Text(*parts: Any, style: StyleProp = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, ref: Optional[Ref] = None, key: Optional[str] = None) -> Element

Display a string of text, optionally with styled nested spans.

Style properties: font_size, color, bold, font_weight, font_family, italic, text_align, background_color, max_lines, letter_spacing, line_height, text_decoration ("underline" / "line_through"), border_radius, border_width, border_color, shadow_*, opacity, transform, plus the common layout props.

Rich text: pass multiple parts, mixing plain strings and nested Text elements, to render one paragraph with per-span styling (a single TextView / UILabel natively, so line wrapping flows across spans):

pn.Text(
    "Hello, ",
    pn.Text("world", style=pn.style(bold=True, color="#0A84FF")),
    "!",
    style=pn.style(font_size=18),
)

Nested spans inherit the outer element's text styling and may override color, background_color, font_size, font_family, font_weight, bold, italic, text_decoration, and letter_spacing.

Parameters:

Name	Type	Description	Default
`*parts`	`Any`	Text content: a single string, or any mix of strings and nested `Text` elements for rich text.	`()`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`accessibility_label`	`Optional[str]`	Spoken description for screen readers.	`None`
`accessibility_hint`	`Optional[str]`	Spoken extra detail (iOS only).	`None`
`accessibility_role`	`Optional[str]`	Semantic role for assistive tech.	`None`
`accessible`	`Optional[bool]`	Override whether the element is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`ref`	`Optional[Ref]`	Optional `Ref` from `use_ref()`.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

Button ¶

Button(title: str = '', *, on_press: Optional[Callable[[], None]] = None, enabled: bool = True, style: StyleProp = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, ref: Optional[Ref] = None, key: Optional[str] = None) -> Element

Display a tappable button.

Style properties: color, background_color, font_size, border_radius, border_width, border_color, shadow_*, opacity, transform, plus the common layout props.

Buttons get accessibility_role="button" by default.

Parameters:

Name	Type	Description	Default
`title`	`str`	Button label.	`''`
`on_press`	`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`	`StyleProp`	Style dict (or list of dicts).	`None`
`accessibility_label`	`Optional[str]`	Spoken description for screen readers.	`None`
`accessibility_hint`	`Optional[str]`	Spoken extra detail (iOS only).	`None`
`accessibility_role`	`Optional[str]`	Override the default `"button"` role.	`None`
`accessible`	`Optional[bool]`	Override whether the element is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`ref`	`Optional[Ref]`	Optional `Ref` from `use_ref()`.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

TextInput ¶

TextInput(*, value: str = '', placeholder: Optional[str] = None, on_change: Optional[Callable[[str], None]] = None, on_submit: Optional[Callable[[str], None]] = None, secure: bool = False, multiline: bool = False, keyboard_type: Optional[KeyboardType] = None, auto_capitalize: Optional[AutoCapitalize] = None, auto_correct: Optional[bool] = None, auto_focus: bool = False, return_key_type: Optional[ReturnKeyType] = None, max_length: Optional[int] = None, placeholder_color: Optional[Color] = None, editable: bool = True, clear_button: bool = False, on_focus: Optional[Callable[[], None]] = None, on_blur: Optional[Callable[[], None]] = None, selection_color: Optional[Color] = None, text_content_type: Optional[str] = None, style: StyleProp = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, ref: Optional[Ref] = None, key: Optional[str] = None) -> Element

Display a text-entry field (single-line by default, or multiline).

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

Parameters:

Name	Type	Description	Default
`value`	`str`	Current text content (controlled-input pattern).	`''`
`placeholder`	`Optional[str]`	Hint shown when `value` is empty.	`None`
`on_change`	`Optional[Callable[[str], None]]`	Callback invoked with the new string each keystroke.	`None`
`on_submit`	`Optional[Callable[[str], None]]`	Callback invoked when the user submits (Return / Done / etc.). Receives the final text.	`None`
`secure`	`bool`	When `True`, characters are masked (use for passwords).	`False`
`multiline`	`bool`	When `True`, allows multiple lines of input.	`False`
`keyboard_type`	`Optional[KeyboardType]`	One of `"default"`, `"email_address"`, `"number_pad"`, `"decimal_pad"`, `"phone_pad"`, `"url"`.	`None`
`auto_capitalize`	`Optional[AutoCapitalize]`	One of `"none"`, `"sentences"`, `"words"`, `"characters"`.	`None`
`auto_correct`	`Optional[bool]`	Enable/disable autocorrection.	`None`
`auto_focus`	`bool`	Request focus on mount.	`False`
`return_key_type`	`Optional[ReturnKeyType]`	One of `"default"`, `"done"`, `"go"`, `"next"`, `"send"`, `"search"`.	`None`
`max_length`	`Optional[int]`	Maximum number of characters allowed.	`None`
`placeholder_color`	`Optional[Color]`	Color used for the placeholder string.	`None`
`editable`	`bool`	When `False`, the field is read-only (still selectable).	`True`
`clear_button`	`bool`	When `True`, shows a clear ("x") button while editing (iOS `clearButtonMode`; an inline button on Android).	`False`
`on_focus`	`Optional[Callable[[], None]]`	Callback invoked when the field gains focus.	`None`
`on_blur`	`Optional[Callable[[], None]]`	Callback invoked when the field loses focus.	`None`
`selection_color`	`Optional[Color]`	Cursor / selection highlight color.	`None`
`text_content_type`	`Optional[str]`	Semantic content hint for autofill (e.g. `"username"`, `"password"`, `"one_time_code"`).	`None`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`accessibility_label`	`Optional[str]`	Spoken description for screen readers.	`None`
`accessibility_hint`	`Optional[str]`	Spoken extra detail (iOS only).	`None`
`accessible`	`Optional[bool]`	Override whether the element is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`ref`	`Optional[Ref]`	Optional `Ref` from `use_ref()`.	`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[ScaleType] = None, tint_color: Optional[Color] = None, placeholder_color: Optional[Color] = None, on_load: Optional[Callable[[], None]] = None, on_error: Optional[Callable[[str], None]] = None, style: StyleProp = None, accessibility_label: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, ref: Optional[Ref] = None, key: Optional[str] = None) -> Element

Display an image from a resource path or URL.

Style properties: background_color, border_*, opacity, transform, plus the common layout props.

Network images (http:// / https://) go through the shared image pipeline (pythonnative.images): downloads happen on a background thread, bytes are cached in memory and on disk keyed by URL, concurrent requests for the same URL share one download, and large bitmaps are downsampled to the view size when decoded.

Parameters:

Name	Type	Description	Default
`source`	`str`	Image resource name or URL.	`''`
`scale_type`	`Optional[ScaleType]`	Fit mode: `"cover"`, `"contain"`, `"stretch"`, `"center"`.	`None`
`tint_color`	`Optional[Color]`	Color overlay applied to template images (monochrome icons).	`None`
`placeholder_color`	`Optional[Color]`	Background color shown while a remote image is loading (and left in place if it fails).	`None`
`on_load`	`Optional[Callable[[], None]]`	Callback invoked once the image has been decoded and displayed.	`None`
`on_error`	`Optional[Callable[[str], None]]`	Callback invoked with an error message when a remote image fails to download or decode.	`None`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`accessibility_label`	`Optional[str]`	Spoken description for screen readers.	`None`
`accessibility_role`	`Optional[str]`	Override the default `"image"` role.	`None`
`accessible`	`Optional[bool]`	Override whether the element is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`ref`	`Optional[Ref]`	Optional `Ref` from `use_ref()`.	`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, accessibility_label: Optional[str] = None, style: StyleProp = 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`
`accessibility_label`	`Optional[str]`	Label exposed to assistive technology (and UI test drivers) for the switch.	`None`
`style`	`StyleProp`	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, color: Optional[Color] = None, track_color: Optional[Color] = None, indeterminate: bool = False, style: StyleProp = None, key: Optional[str] = None) -> Element

Show determinate progress as a value between 0.0 and 1.0.

For a spinner instead of a bar, use ActivityIndicator; for an indeterminate bar pass indeterminate=True.

Parameters:

Name	Type	Description	Default
`value`	`float`	Fraction complete (clamped to `[0.0, 1.0]` by the platform handler).	`0.0`
`color`	`Optional[Color]`	Color of the filled portion of the bar.	`None`
`track_color`	`Optional[Color]`	Color of the unfilled track behind the fill.	`None`
`indeterminate`	`bool`	When `True`, the bar animates continuously and `value` is ignored.	`False`
`style`	`StyleProp`	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, color: Optional[Color] = None, size: Literal['small', 'large'] = 'small', style: StyleProp = 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`
`color`	`Optional[Color]`	Spinner color.	`None`
`size`	`Literal['small', 'large']`	`"small"` (default) or `"large"`.	`'small'`
`style`	`StyleProp`	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 = '', html: Optional[str] = None, on_load: Optional[Callable[[str], None]] = None, on_message: Optional[Callable[[str], None]] = None, on_navigation_state_change: Optional[Callable[[str], None]] = None, inject_javascript: Optional[str] = None, scroll_enabled: bool = True, style: StyleProp = None, key: Optional[str] = None) -> Element

Embed web content from a URL or an inline HTML string.

Parameters:

Name	Type	Description	Default
`url`	`str`	HTTP(S) URL to load. Ignored when `html` is given.	`''`
`html`	`Optional[str]`	Inline HTML markup to render instead of loading a URL.	`None`
`on_load`	`Optional[Callable[[str], None]]`	Callback invoked with the final URL once a page finishes loading.	`None`
`on_message`	`Optional[Callable[[str], None]]`	Callback invoked with the string payload whenever page JavaScript calls `window.pythonnative.postMessage(...)`.	`None`
`on_navigation_state_change`	`Optional[Callable[[str], None]]`	Callback invoked with the URL each time the top-level document begins navigating.	`None`
`inject_javascript`	`Optional[str]`	JavaScript evaluated after each page load (useful for installing the `postMessage` bridge or tweaking the DOM).	`None`
`scroll_enabled`	`bool`	When `False`, disables scrolling inside the web content.	`True`
`style`	`StyleProp`	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. Mirrored on both axes: whichever axis the parent's `flex_direction` chooses as main becomes the actual gap.	`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, accessibility_label: Optional[str] = None, style: StyleProp = 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`
`accessibility_label`	`Optional[str]`	Label exposed to assistive technology (and UI test drivers) for the slider.	`None`
`style`	`StyleProp`	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: StyleProp = None, gestures: Optional[List[Any]] = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, ref: Optional[Ref] = None, key: Optional[str] = None) -> Element

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

Defaults to flex_direction: "column" (override via style).

Flex container properties (passed via style):

flex_direction: "column" (default), "row", "column_reverse", "row_reverse".
flex_wrap: "nowrap" (default), "wrap", "wrap_reverse", with align_content controlling how wrapped lines share leftover cross-axis space.
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".
direction: "ltr" (default) or "rtl". Flips rows and resolves margin_start / padding_end / absolute start / end insets.
overflow: "visible" (default) or "hidden".
spacing (alias gap; per-axis row_gap / column_gap), padding, background_color, border_radius, border_width, border_color, shadow_color, shadow_offset, shadow_opacity, shadow_radius, elevation, opacity, transform.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Child elements rendered inside the container.	`()`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`gestures`	`Optional[List[Any]]`	Optional list of gesture descriptors from `pythonnative.gestures` (e.g. `[gestures.Pan(on_change=…)]`) recognized natively on this view.	`None`
`accessibility_label`	`Optional[str]`	Spoken description for screen readers.	`None`
`accessibility_hint`	`Optional[str]`	Spoken extra detail (iOS only).	`None`
`accessibility_role`	`Optional[str]`	Semantic role for assistive tech.	`None`
`accessible`	`Optional[bool]`	Override whether the element is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`ref`	`Optional[Ref]`	Optional `Ref` from `use_ref()`.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

Column ¶

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

Arrange children vertically.

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

Parameters:

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

Returns:

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

Row ¶

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

Arrange children horizontally.

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

Parameters:

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

Returns:

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

ScrollView ¶

ScrollView(*children: Element, refresh_control: Optional[Dict[str, Any]] = None, scroll_axis: Optional[Literal['vertical', 'horizontal']] = None, on_scroll: Optional[Callable[[Dict[str, float]], None]] = None, shows_scroll_indicator: bool = True, paging_enabled: bool = False, bounces: bool = True, content_container_style: StyleProp = None, keyboard_dismiss_mode: Optional[Literal['none', 'on_drag', 'interactive']] = None, style: StyleProp = None, ref: Optional[Ref] = None, key: Optional[str] = None) -> Element

Wrap children in a scrollable container.

ScrollView typically takes a single child (a Column or Row aggregating the scrollable content). It accepts *children for ergonomic call sites; the underlying native scroll view stacks them on its content axis.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Child elements to scroll.	`()`
`refresh_control`	`Optional[Dict[str, Any]]`	Optional pull-to-refresh spec, typically constructed via `RefreshControl`. The dict must have `refreshing` (bool) and `on_refresh` (callable).	`None`
`scroll_axis`	`Optional[Literal['vertical', 'horizontal']]`	`"vertical"` (default) or `"horizontal"`.	`None`
`on_scroll`	`Optional[Callable[[Dict[str, float]], None]]`	Callback invoked with `{"x": …, "y": …}` content offsets as the user scrolls.	`None`
`shows_scroll_indicator`	`bool`	When `False`, hides the scroll bar.	`True`
`paging_enabled`	`bool`	When `True`, the scroll view snaps to multiples of its own size (carousel behavior).	`False`
`bounces`	`bool`	When `False`, disables the iOS rubber-band overscroll.	`True`
`content_container_style`	`StyleProp`	Style applied to the inner content wrapper (padding, alignment, spacing of the scrollable content), distinct from `style` (the scroll view frame).	`None`
`keyboard_dismiss_mode`	`Optional[Literal['none', 'on_drag', 'interactive']]`	`"none"` (default), `"on_drag"`, or `"interactive"`. Controls whether scrolling dismisses the keyboard.	`None`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`ref`	`Optional[Ref]`	Optional `Ref` from `use_ref()`.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

SafeAreaView ¶

SafeAreaView(*children: Element, edges: Optional[Tuple[Literal['top', 'left', 'bottom', 'right'], ...]] = None, style: StyleProp = None, key: Optional[str] = None) -> Element

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

Applies the platform-reported insets as extra padding on the selected edges and re-renders automatically when the insets change (rotation, split view). User padding on an inset edge is added to the inset, matching react-native-safe-area-context.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Child elements that should avoid system UI overlays.	`()`
`edges`	`Optional[Tuple[Literal['top', 'left', 'bottom', 'right'], ...]]`	Which edges to pad; defaults to all four.	`None`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` that renders a
`Element`	`"SafeAreaView"` container.

Modal ¶

Modal(*children: Element, visible: bool = False, on_dismiss: Optional[Callable[[], None]] = None, on_show: Optional[Callable[[], None]] = None, title: Optional[str] = None, animation_type: Literal['slide', 'fade', 'none'] = 'slide', transparent: bool = False, presentation_style: Literal['page_sheet', 'form_sheet', 'full_screen', 'overlay'] = 'page_sheet', dismiss_on_backdrop: bool = True, style: StyleProp = None, key: Optional[str] = None) -> Element

Overlay modal dialog backed by a real native presentation.

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. On iOS this presents a UIViewController; on Android it shows an android.app.Dialog.

Children are mounted as the modal's content view, not into the on-tree placeholder, so they appear above all other native content and don't influence the underlying layout.

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.	`None`
`on_show`	`Optional[Callable[[], None]]`	Callback invoked once the modal has finished presenting.	`None`
`title`	`Optional[str]`	Optional title-bar text.	`None`
`animation_type`	`Literal['slide', 'fade', 'none']`	`"slide"` (default), `"fade"`, or `"none"`.	`'slide'`
`transparent`	`bool`	When `True`, the underlying view is dimmed instead of fully covered.	`False`
`presentation_style`	`Literal['page_sheet', 'form_sheet', 'full_screen', 'overlay']`	iOS presentation style, `"page_sheet"` (default), `"form_sheet"`, `"full_screen"`, or `"overlay"` (custom dimmed overlay). On Android, `"overlay"` keeps the dialog non-fullscreen.	`'page_sheet'`
`dismiss_on_backdrop`	`bool`	When `True` (default) and `transparent` / `"overlay"`, tapping the dimmed backdrop dismisses the modal.	`True`
`style`	`StyleProp`	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(*children: Element, on_press: Optional[Callable[[], None]] = None, on_long_press: Optional[Callable[[], None]] = None, on_press_in: Optional[Callable[[], None]] = None, on_press_out: Optional[Callable[[], None]] = None, pressed_opacity: float = 0.6, gestures: Optional[List[Any]] = None, style: Union[StyleProp, Callable[[Dict[str, bool]], StyleProp]] = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, ref: Optional[Ref] = None, key: Optional[str] = None) -> Element

Wrap children with tap / long-press / gesture handlers.

Useful for making non-button elements (text, images, custom views) respond to user taps. The wrapper view fades to pressed_opacity on touch-down and back to full opacity on touch-up.

Pressable gets accessibility_role="button" by default.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Elements to make pressable.	`()`
`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`
`on_press_in`	`Optional[Callable[[], None]]`	Callback invoked the moment the press starts.	`None`
`on_press_out`	`Optional[Callable[[], None]]`	Callback invoked when the press lifts or cancels.	`None`
`pressed_opacity`	`float`	Opacity (0–1) applied while the user's finger is down. Set to `1.0` for no visual feedback.	`0.6`
`gestures`	`Optional[List[Any]]`	Optional list of gesture descriptors from `pythonnative.gestures` recognized natively on this view (pan / swipe / pinch / rotation / multi-tap).	`None`
`style`	`Union[StyleProp, Callable[[Dict[str, bool]], StyleProp]]`	Style dict applied to the wrapper, or a callable receiving the interaction state (`{"pressed": bool}`) and returning a style, re-evaluated on every press transition: `pn.Pressable( pn.Text("Tap"), style=lambda s: pn.style( background_color="#0051A8" if s["pressed"] else "#007AFF", ), )`	`None`
`accessibility_label`	`Optional[str]`	Spoken description for screen readers.	`None`
`accessibility_hint`	`Optional[str]`	Spoken extra detail (iOS only).	`None`
`accessibility_role`	`Optional[str]`	Override the default `"button"` role.	`None`
`accessible`	`Optional[bool]`	Override whether the element is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`ref`	`Optional[Ref]`	Optional `Ref` from `use_ref()`.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"Pressable"`
`Element`	(wrapped in a stateful composite when `style` is callable).

TouchableOpacity ¶

TouchableOpacity(*children: Element, on_press: Optional[Callable[[], None]] = None, on_long_press: Optional[Callable[[], None]] = None, active_opacity: float = 0.2, disabled: bool = False, style: StyleProp = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, key: Optional[str] = None) -> Element

Wrap children so they fade to active_opacity while pressed.

A thin ergonomic alias over Pressable that mirrors React Native's TouchableOpacity: the only visual feedback is an opacity dip on touch-down. When disabled is set, the press callbacks are dropped so the wrapper is inert.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Elements to make tappable.	`()`
`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`
`active_opacity`	`float`	Opacity (0–1) applied while the finger is down.	`0.2`
`disabled`	`bool`	When `True`, ignores presses and renders at reduced opacity.	`False`
`style`	`StyleProp`	Style dict applied to the wrapper.	`None`
`accessibility_label`	`Optional[str]`	Spoken description for screen readers.	`None`
`accessibility_hint`	`Optional[str]`	Spoken extra detail (iOS only).	`None`
`accessibility_role`	`Optional[str]`	Override the default `"button"` role.	`None`
`accessible`	`Optional[bool]`	Override whether the element is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

ImageBackground ¶

ImageBackground(*children: Element, source: str = '', scale_type: Optional[ScaleType] = None, style: StyleProp = None, accessibility_label: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, key: Optional[str] = None) -> Element

Render children layered on top of a background image.

Composed entirely from existing primitives: an absolutely-filled Image sits behind a content View holding children. The container's style controls sizing/padding; the image stretches to fill it via position: "absolute" and zeroed insets.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Foreground content drawn over the image.	`()`
`source`	`str`	Image resource name or URL.	`''`
`scale_type`	`Optional[ScaleType]`	Background fit mode (`"cover"` is the most common for backgrounds).	`None`
`style`	`StyleProp`	Style dict for the container (size, padding, alignment).	`None`
`accessibility_label`	`Optional[str]`	Spoken description of the background image.	`None`
`accessible`	`Optional[bool]`	Override whether the image is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` of type `"View"` wrapping
`Element`	the background image and foreground content.

Checkbox ¶

Checkbox(*, value: bool = False, on_change: Optional[Callable[[bool], None]] = None, label: Optional[str] = None, disabled: bool = False, color: Optional[Color] = None, style: StyleProp = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, key: Optional[str] = None) -> Element

A boolean checkbox with an optional inline label.

Backed by android.widget.CheckBox on Android and a checkmark UIButton on iOS. Tapping the control (or its label) toggles the value and fires on_change(new_value).

Parameters:

Name	Type	Description	Default
`value`	`bool`	Current checked state.	`False`
`on_change`	`Optional[Callable[[bool], None]]`	Callback invoked with the new boolean state.	`None`
`label`	`Optional[str]`	Optional text shown beside the box (also tappable).	`None`
`disabled`	`bool`	When `True`, the control is greyed out and inert.	`False`
`color`	`Optional[Color]`	Tint applied to the checked box.	`None`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`accessibility_label`	`Optional[str]`	Spoken description for screen readers.	`None`
`accessibility_hint`	`Optional[str]`	Spoken extra detail (iOS only).	`None`
`accessible`	`Optional[bool]`	Override whether the element is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

SegmentedControl ¶

SegmentedControl(*, segments: Optional[List[str]] = None, selected_index: int = 0, on_change: Optional[Callable[[int], None]] = None, enabled: bool = True, tint_color: Optional[Color] = None, style: StyleProp = None, accessibility_label: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, key: Optional[str] = None) -> Element

A horizontal multi-choice control (one selected segment at a time).

Backed by UISegmentedControl on iOS and a styled toggle row on Android. Selecting a segment fires on_change(index).

Parameters:

Name	Type	Description	Default
`segments`	`Optional[List[str]]`	Ordered list of segment labels.	`None`
`selected_index`	`int`	Index of the currently selected segment.	`0`
`on_change`	`Optional[Callable[[int], None]]`	Callback invoked with the newly selected index.	`None`
`enabled`	`bool`	When `False`, the control is disabled.	`True`
`tint_color`	`Optional[Color]`	Accent color for the selected segment.	`None`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`accessibility_label`	`Optional[str]`	Spoken description for screen readers.	`None`
`accessible`	`Optional[bool]`	Override whether the element is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

DatePicker ¶

DatePicker(*, value: Optional[str] = None, mode: Literal['date', 'time', 'datetime'] = 'date', on_change: Optional[Callable[[str], None]] = None, minimum: Optional[str] = None, maximum: Optional[str] = None, enabled: bool = True, style: StyleProp = None, accessibility_label: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, key: Optional[str] = None) -> Element

A native date / time picker.

Backed by UIDatePicker on iOS and a trigger button that opens the platform DatePickerDialog / TimePickerDialog on Android. value and the value reported to on_change are ISO-8601 strings ("2026-05-31" for mode="date", "14:30" for mode="time", "2026-05-31T14:30" for mode="datetime"), so values stay JSON-serializable and platform-agnostic.

Parameters:

Name	Type	Description	Default
`value`	`Optional[str]`	Currently selected value as an ISO-8601 string.	`None`
`mode`	`Literal['date', 'time', 'datetime']`	`"date"` (default), `"time"`, or `"datetime"`.	`'date'`
`on_change`	`Optional[Callable[[str], None]]`	Callback invoked with the new ISO-8601 string.	`None`
`minimum`	`Optional[str]`	Earliest selectable value (ISO-8601), if any.	`None`
`maximum`	`Optional[str]`	Latest selectable value (ISO-8601), if any.	`None`
`enabled`	`bool`	When `False`, the picker is disabled.	`True`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`accessibility_label`	`Optional[str]`	Spoken description for screen readers.	`None`
`accessible`	`Optional[bool]`	Override whether the element is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

Fragment ¶

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

Group children without adding a wrapping native view.

Like React's <></>: groups elements without introducing an extra container. Each child mounts as a direct sibling of the Fragment's position in the parent's child list. Components may also simply return a plain list of elements; Fragment exists for when the group needs a key (e.g. rendering a list of pairs) or when a single expression reads better.

pn.Column(
    pn.Text("Top"),
    pn.Fragment(
        pn.Text("Middle A"),
        pn.Text("Middle B"),
    ),
    pn.Text("Bottom"),
)

Parameters:

Name	Type	Description	Default
`*children`	`Optional[Element]`	Child elements to expose at the parent level. `None` and `False` children are dropped, which makes conditional rendering with `cond and pn.Text(...)` ergonomic.	`()`
`key`	`Optional[str]`	Stable identity for keyed reconciliation. A keyed Fragment moves all of its children as one unit and preserves their state across reorders.	`None`

Returns:

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

Portal ¶

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

Render children into a full-screen overlay above everything else.

Like React DOM's createPortal: the children stay part of this component's tree for state, context, and events, but their native views mount in a transparent overlay attached to the window (above the screen's content) instead of inside the surrounding parent. Use it for toasts, dropdowns, tooltips, and lightweight custom overlays that must escape overflow: "hidden" ancestors. For a system-styled dialog with its own presentation and dismissal gestures, use Modal instead.

The overlay itself does not intercept touches; only the children themselves are hit-testable. Children are laid out against the full viewport, so position them with absolute insets:

pn.Portal(
    pn.View(
        pn.Text("Saved!"),
        style=pn.style(position="absolute", bottom=40, left=40, right=40),
    ),
)

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Overlay content.	`()`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

ErrorBoundary ¶

ErrorBoundary(*children: Element, fallback: Optional[Any] = None, on_error: Optional[Callable[[BaseException], None]] = None, key: Optional[str] = None) -> Element

Catch render errors in the wrapped subtree and display fallback instead.

When any descendant raises during render (initial mount, a parent re-render, or a local state-driven update), the failed subtree is torn down and fallback is mounted in its place. Without a boundary the error propagates to the screen host (which shows the dev error overlay in dev mode).

fallback may be:

An Element, shown as-is.
fallback(error) -> Element.
fallback(error, reset) -> Element, where reset is a zero-arg callable that clears the error and remounts the original children (fresh state), for retry buttons.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Subtree to wrap.	`()`
`fallback`	`Optional[Any]`	Fallback content (see above). Required for the boundary to actually catch; without it errors propagate to the next boundary up.	`None`
`on_error`	`Optional[Callable[[BaseException], None]]`	Callback invoked with the exception when the boundary catches, before the fallback mounts. Use it for error reporting.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

Example

import pythonnative as pn

pn.ErrorBoundary(
    MyRiskyComponent(),
    fallback=lambda err, reset: pn.Column(
        pn.Text(f"Error: {err}"),
        pn.Button("Retry", on_press=reset),
    ),
    on_error=lambda err: log.exception(err),
)

FlatList ¶

FlatList(*, data: Optional[List[Any]] = None, render_item: Optional[Callable[[Any, int], Element]] = None, key_extractor: Optional[Callable[[Any, int], str]] = None, item_height: Optional[float] = None, get_item_height: Optional[Callable[[Any, int], float]] = None, estimated_item_height: Optional[float] = None, separator_height: float = 0, refresh_control: Optional[Dict[str, Any]] = None, horizontal: bool = False, num_columns: int = 1, list_header: Optional[Element] = None, list_footer: Optional[Element] = None, list_empty: Optional[Element] = None, on_end_reached: Optional[Callable[[], None]] = None, on_end_reached_threshold: float = 0.5, on_viewable_items_changed: Optional[Callable[[List[Dict[str, Any]]], None]] = None, on_scroll: Optional[Callable[[Dict[str, float]], None]] = None, shows_scroll_indicator: bool = True, content_container_style: StyleProp = None, style: StyleProp = None, ref: Optional[Ref] = None, key: Optional[str] = None) -> Element

Virtualized scrollable list that renders items from data lazily.

Only the rows inside (and just beyond) the viewport are mounted; leading and trailing spacers stand in for everything else, and the window shifts as the user scrolls. Rows may have variable heights: pass item_height when rows are uniform, get_item_height for exact per-item extents, or nothing at all; unknown rows start at estimated_item_height and are corrected with their measured extent once they've been on screen.

Pass a Ref (from use_ref) to receive a ListController on ref.current: ref.current.scroll_to_index(i), ref.current.scroll_to_offset(pts), and ref.current.scroll_to_end().

Parameters:

Name	Type	Description	Default
`data`	`Optional[List[Any]]`	List of arbitrary item values.	`None`
`render_item`	`Optional[Callable[[Any, int], Element]]`	`render_item(item, index) -> Element`. Defaults to wrapping each item in a `Text`.	`None`
`key_extractor`	`Optional[Callable[[Any, int], str]]`	Function returning a stable key per item (recommended whenever `data` can reorder).	`None`
`item_height`	`Optional[float]`	Uniform row extent in points, when known.	`None`
`get_item_height`	`Optional[Callable[[Any, int], float]]`	`get_item_height(item, index) -> float` for exact variable extents without measurement.	`None`
`estimated_item_height`	`Optional[float]`	Starting extent estimate for rows whose true size isn't known yet (default 44).	`None`
`separator_height`	`float`	Gap below each row, in points.	`0`
`refresh_control`	`Optional[Dict[str, Any]]`	Optional pull-to-refresh spec from `RefreshControl`.	`None`
`horizontal`	`bool`	Scroll horizontally (extents become widths).	`False`
`num_columns`	`int`	Render items in a grid of this many columns.	`1`
`list_header`	`Optional[Element]`	Element rendered once before all rows.	`None`
`list_footer`	`Optional[Element]`	Element rendered once after all rows.	`None`
`list_empty`	`Optional[Element]`	Element rendered when `data` is empty.	`None`
`on_end_reached`	`Optional[Callable[[], None]]`	Called when the user scrolls within `on_end_reached_threshold` viewports of the end (fires once per data length).	`None`
`on_end_reached_threshold`	`float`	Distance from the end, in viewport multiples, at which `on_end_reached` fires.	`0.5`
`on_viewable_items_changed`	`Optional[Callable[[List[Dict[str, Any]]], None]]`	Called with a list of `{"index", "key", "item"}` dicts whenever the set of visible rows changes.	`None`
`on_scroll`	`Optional[Callable[[Dict[str, float]], None]]`	Called with the raw scroll payload (`{"x": …, "y": …}`).	`None`
`shows_scroll_indicator`	`bool`	When `False`, hides the scroll bar.	`True`
`content_container_style`	`StyleProp`	Style applied to the inner content wrapper.	`None`
`style`	`StyleProp`	Style for the outer scroll container.	`None`
`ref`	`Optional[Ref]`	Optional `Ref`; receives a `ListController` on `ref.current` after mount.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation of the list.	`None`

Returns:

Type	Description
`Element`	A virtualized list element (a function component instance).

Example

import pythonnative as pn

items = [{"id": i, "name": f"Item {i}"} for i in range(10000)]

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

SectionList ¶

SectionList(*, sections: Optional[List[Dict[str, Any]]] = None, render_item: Optional[Callable[[Any, int, int], Element]] = None, render_section_header: Optional[Callable[[Dict[str, Any], int], Element]] = None, key_extractor: Optional[Callable[[Any, int], str]] = None, item_height: Optional[float] = None, get_item_height: Optional[Callable[[Any, int, int], float]] = None, estimated_item_height: Optional[float] = None, section_header_height: Optional[float] = None, separator_height: float = 0, refresh_control: Optional[Dict[str, Any]] = None, list_header: Optional[Element] = None, list_footer: Optional[Element] = None, list_empty: Optional[Element] = None, on_end_reached: Optional[Callable[[], None]] = None, on_end_reached_threshold: float = 0.5, on_scroll: Optional[Callable[[Dict[str, float]], None]] = None, style: StyleProp = None, ref: Optional[Ref] = None, key: Optional[str] = None) -> Element

Virtualized list with section headers interleaved between row groups.

Flattens sections into a single virtualized sequence where each entry is either a header or an item, then reuses the same windowing engine as FlatList; headers and items may have different (and variable) heights.

Parameters:

Name	Type	Description	Default
`sections`	`Optional[List[Dict[str, Any]]]`	Each section is `{"title": ..., "data": [...]}`.	`None`
`render_item`	`Optional[Callable[[Any, int, int], Element]]`	`render_item(item, item_index, section_index) -> Element`.	`None`
`render_section_header`	`Optional[Callable[[Dict[str, Any], int], Element]]`	`render_section_header(section, section_index) -> Element`. Defaults to a bold `Text` of the section title.	`None`
`key_extractor`	`Optional[Callable[[Any, int], str]]`	Stable key per item: `key_extractor(item, item_index) -> str`.	`None`
`item_height`	`Optional[float]`	Uniform item extent in points, when known.	`None`
`get_item_height`	`Optional[Callable[[Any, int, int], float]]`	`get_item_height(item, item_index, section_index) -> float` for exact variable extents.	`None`
`estimated_item_height`	`Optional[float]`	Starting estimate for unmeasured rows.	`None`
`section_header_height`	`Optional[float]`	Header extent in points, when known.	`None`
`separator_height`	`float`	Gap below each item, in points.	`0`
`refresh_control`	`Optional[Dict[str, Any]]`	Optional pull-to-refresh spec.	`None`
`list_header`	`Optional[Element]`	Element rendered once before everything.	`None`
`list_footer`	`Optional[Element]`	Element rendered once after everything.	`None`
`list_empty`	`Optional[Element]`	Element rendered when there are no sections.	`None`
`on_end_reached`	`Optional[Callable[[], None]]`	Called near the end of the content.	`None`
`on_end_reached_threshold`	`float`	Distance from the end, in viewport multiples, at which `on_end_reached` fires.	`0.5`
`on_scroll`	`Optional[Callable[[Dict[str, float]], None]]`	Called with the raw scroll payload.	`None`
`style`	`StyleProp`	Style for the outer scroll container.	`None`
`ref`	`Optional[Ref]`	Optional `Ref`; receives a `ListController` on `ref.current` after mount.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation of the list.	`None`

Returns:

Type	Description
`Element`	A virtualized list element (a function component instance).

StatusBar ¶

StatusBar(*, bar_style: Optional[Literal['light', 'dark', 'default']] = None, background_color: Optional[Color] = None, hidden: Optional[bool] = None, key: Optional[str] = None) -> Element

Configure the device's status bar appearance.

StatusBar is a side-effect element: it doesn't render any visible content but applies its props to the host platform's status bar. Mount one near the top of your tree.

The bar_style parameter is named separately from the universal style kwarg (which is unused here) to avoid the conflict that style="light" would create with the visual-style dict used elsewhere.

Parameters:

Name	Type	Description	Default
`bar_style`	`Optional[Literal['light', 'dark', 'default']]`	`"light"` (light icons over dark backgrounds), `"dark"` (dark icons over light backgrounds), or `"default"` (system default).	`None`
`background_color`	`Optional[Color]`	Color of the status-bar background (Android only; iOS draws the bar transparent over your content).	`None`
`hidden`	`Optional[bool]`	When `True`, the status bar is hidden.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

KeyboardAvoidingView ¶

KeyboardAvoidingView(*children: Element, behavior: Literal['padding', 'position'] = 'padding', keyboard_vertical_offset: float = 0.0, style: StyleProp = None, key: Optional[str] = None) -> Element

Wrap content that should shift up when the keyboard is shown.

Subscribes to the platform-reported keyboard height (via use_keyboard_height internally) and shifts its content so the focused text input stays visible. On iOS the height comes from UIKeyboardWillShowNotification; on Android from the window's IME insets.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Children rendered inside the avoiding container.	`()`
`behavior`	`Literal['padding', 'position']`	`"padding"` (adds bottom padding, resizing the content) or `"position"` (translates the container upward without resizing).	`'padding'`
`keyboard_vertical_offset`	`float`	Distance in layout units already covered by other UI (e.g. a nav bar); subtracted from the keyboard height before applying the shift.	`0.0`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

Type	Description
`Element`	An `Element` that renders a
`Element`	`"KeyboardAvoidingView"` container.

RefreshControl ¶

RefreshControl(*, refreshing: bool = False, on_refresh: Optional[Callable[[], None]] = None, tint_color: Optional[Color] = None) -> Dict[str, Any]

Pull-to-refresh spec for ScrollView / FlatList.

Returns a plain dict that should be passed as the refresh_control= prop. Modeled as a dict (not an Element) so the host scroll container can hold one without it appearing as a child node.

Parameters:

Name	Type	Description	Default
`refreshing`	`bool`	Drive the spinner's visibility from a use_state value.	`False`
`on_refresh`	`Optional[Callable[[], None]]`	Callback invoked when the user pulls down past the threshold. Set `refreshing` to `True` for the duration of the work, then back to `False` on completion.	`None`
`tint_color`	`Optional[Color]`	Color of the spinner.	`None`

Returns:

Type	Description
`Dict[str, Any]`	Dict suitable for the `refresh_control` prop on a scroll
`Dict[str, Any]`	container.

Example

import pythonnative as pn

@pn.component
def MyList():
    refreshing, set_refreshing = pn.use_state(False)

    def reload():
        set_refreshing(True)
        # ... fetch data ...
        set_refreshing(False)

    return pn.ScrollView(
        pn.Text("Pull me!"),
        refresh_control=pn.RefreshControl(
            refreshing=refreshing, on_refresh=reload
        ),
    )

Picker ¶

Picker(*, value: Any = None, items: Optional[List[Dict[str, Any]]] = None, on_change: Optional[Callable[[Any], None]] = None, placeholder: str = 'Select…', style: StyleProp = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessible: Optional[bool] = None, accessibility_state: Optional[AccessibilityState] = None, accessibility_live_region: Optional[Literal['none', 'polite', 'assertive']] = None, test_id: Optional[str] = None, ref: Optional[Ref] = None, key: Optional[str] = None) -> Element

A real native dropdown / select widget.

Renders a tappable trigger labelled with the selected item; the iOS handler attaches a UIMenu (system dropdown) and the Android handler uses a native Spinner. Selecting an item fires on_change(value).

items is an ordered list of {"value": Any, "label": str} entries (label defaults to str(value) when omitted).

Parameters:

Name	Type	Description	Default
`value`	`Any`	Currently selected value (matched against `items[i]["value"]`).	`None`
`items`	`Optional[List[Dict[str, Any]]]`	Selectable options.	`None`
`on_change`	`Optional[Callable[[Any], None]]`	Callback invoked with the new value.	`None`
`placeholder`	`str`	Label shown when no item matches `value`.	`'Select…'`
`style`	`StyleProp`	Style dict applied to the trigger.	`None`
`accessibility_label`	`Optional[str]`	Spoken description for screen readers.	`None`
`accessibility_hint`	`Optional[str]`	Spoken extra detail (iOS only).	`None`
`accessible`	`Optional[bool]`	Override whether the element is exposed to AT.	`None`
`accessibility_state`	`Optional[AccessibilityState]`	Current widget state for assistive tech, e.g. `{"disabled": True, "selected": False}`. Recognized keys: `disabled`, `selected`, `checked`, `busy`, `expanded`.	`None`
`accessibility_live_region`	`Optional[Literal['none', 'polite', 'assertive']]`	How AT announces dynamic changes to this view: `"none"`, `"polite"`, or `"assertive"` (Android only).	`None`
`test_id`	`Optional[str]`	Stable identifier for UI tests; exposed as `resource-id` on Android and `accessibilityIdentifier` on iOS.	`None`
`ref`	`Optional[Ref]`	Optional `Ref` from `use_ref()`.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

Next steps¶

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