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 and the typed prop schemas they share.

Each @dataclass(frozen=True) class in this module — TextProps, ButtonProps, etc. — is the canonical schema for one built-in component. Each factory function (Text, Button, …) is a thin ergonomic 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 same Props dataclasses are used by the pythonnative.sdk surface for third-party components, so the built-in API and the extension API speak the same shape.

Example

import pythonnative as pn

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

Classes:

Name	Description
`TextProps`	Props for `Text`.
`ButtonProps`	Props for `Button`.
`TextInputProps`	Props for `TextInput`.
`ImageProps`	Props for `Image`.
`SwitchProps`	Props for `Switch`.
`ProgressBarProps`	Props for `ProgressBar`.
`ActivityIndicatorProps`	Props for `ActivityIndicator`.
`WebViewProps`	Props for `WebView`.
`SpacerProps`	Props for `Spacer`.
`SliderProps`	Props for `Slider`.
`ViewProps`	Props for `View`, `Column`, and `Row`.
`ScrollViewProps`	Props for `ScrollView`.
`SafeAreaViewProps`	Props for `SafeAreaView`.
`ModalProps`	Props for `Modal`.
`PressableProps`	Props for `Pressable`.
`StatusBarProps`	Props for `StatusBar`.
`KeyboardAvoidingViewProps`	Props for `KeyboardAvoidingView`.
`PickerProps`	Props for `Picker`.

Functions:

Name	Description
`Text`	Display a string of text.
`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.
`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 and long-press handlers.
`Fragment`	Group children without adding a wrapping native view.
`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 that supports section headers.
`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.

TextProps `dataclass` ¶

TextProps(text: str = '', accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None)

Bases: Props

Props for Text.

ButtonProps `dataclass` ¶

ButtonProps(title: str = '', on_click: Optional[Callable[[], None]] = None, enabled: bool = True, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None)

Bases: Props

Props for Button.

TextInputProps `dataclass` ¶

TextInputProps(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, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessible: Optional[bool] = None)

Bases: Props

Props for TextInput.

ImageProps `dataclass` ¶

ImageProps(source: Optional[str] = None, scale_type: Optional[ScaleType] = None, tint_color: Optional[Color] = None, accessibility_label: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None)

Bases: Props

Props for Image.

SwitchProps `dataclass` ¶

SwitchProps(value: bool = False, on_change: Optional[Callable[[bool], None]] = None)

Bases: Props

Props for Switch.

ProgressBarProps `dataclass` ¶

ProgressBarProps(value: float = 0.0)

Bases: Props

Props for ProgressBar.

ActivityIndicatorProps `dataclass` ¶

ActivityIndicatorProps(animating: bool = True)

Bases: Props

Props for ActivityIndicator.

WebViewProps `dataclass` ¶

WebViewProps(url: Optional[str] = None)

Bases: Props

Props for WebView.

SpacerProps `dataclass` ¶

SpacerProps(size: Optional[float] = None, flex: Optional[float] = None)

Bases: Props

Props for Spacer.

SliderProps `dataclass` ¶

SliderProps(value: float = 0.0, min_value: float = 0.0, max_value: float = 1.0, on_change: Optional[Callable[[float], None]] = None)

Bases: Props

Props for Slider.

ViewProps `dataclass` ¶

ViewProps(accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None)

Bases: Props

Props for View, Column, and Row.

ScrollViewProps `dataclass` ¶

ScrollViewProps(refresh_control: Optional[Dict[str, Any]] = None, scroll_axis: Optional[Literal['vertical', 'horizontal']] = None)

Bases: Props

Props for ScrollView.

SafeAreaViewProps `dataclass` ¶

SafeAreaViewProps()

Bases: Props

Props for SafeAreaView.

ModalProps `dataclass` ¶

ModalProps(visible: bool = False, on_dismiss: Optional[Callable[[], None]] = None, title: Optional[str] = None, animation_type: Literal['slide', 'fade', 'none'] = 'slide', transparent: bool = False)

Bases: Props

Props for Modal.

PressableProps `dataclass` ¶

PressableProps(on_press: Optional[Callable[[], None]] = None, on_long_press: Optional[Callable[[], None]] = None, pressed_opacity: float = 0.6, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None)

Bases: Props

Props for Pressable.

StatusBarProps `dataclass` ¶

StatusBarProps(bar_style: Optional[Literal['light', 'dark', 'default']] = None, background_color: Optional[Color] = None, hidden: Optional[bool] = None)

Bases: Props

Props for StatusBar.

KeyboardAvoidingViewProps `dataclass` ¶

KeyboardAvoidingViewProps(behavior: Literal['padding', 'position'] = 'padding')

Bases: Props

Props for KeyboardAvoidingView.

PickerProps `dataclass` ¶

PickerProps(value: Any = None, items: List[Dict[str, Any]] = list(), on_change: Optional[Callable[[Any], None]] = None, placeholder: str = 'Select…', accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessible: Optional[bool] = None)

Bases: Props

Props for Picker.

items is an ordered list of {"value": Any, "label": str} entries. value is matched against items[i]["value"] to determine the currently selected row.

Text ¶

Text(text: str = '', *, style: StyleProp = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None, ref: Optional[Dict[str, Any]] = None, key: Optional[str] = None) -> Element

Display a string of text.

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.

Parameters:

Name	Type	Description	Default
`text`	`str`	Text content to display.	`''`
`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`
`ref`	`Optional[Dict[str, Any]]`	Optional `use_ref()` dict.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

Button ¶

Button(title: str = '', *, on_click: 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, ref: Optional[Dict[str, Any]] = 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_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`	`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`
`ref`	`Optional[Dict[str, Any]]`	Optional `use_ref()` dict.	`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, style: StyleProp = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessible: Optional[bool] = None, ref: Optional[Dict[str, Any]] = 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`
`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`
`ref`	`Optional[Dict[str, Any]]`	Optional `use_ref()` dict.	`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, style: StyleProp = None, accessibility_label: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None, ref: Optional[Dict[str, Any]] = 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://) are loaded asynchronously off the main thread on both iOS (via NSURLSession) and Android (via a worker thread plus BitmapFactory).

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`
`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`
`ref`	`Optional[Dict[str, Any]]`	Optional `use_ref()` dict.	`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: 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`
`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, style: StyleProp = 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`	`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, 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`
`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 = '', style: StyleProp = 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`	`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, 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`
`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, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None, ref: Optional[Dict[str, Any]] = 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".
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, 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`
`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`
`ref`	`Optional[Dict[str, Any]]`	Optional `use_ref()` dict.	`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[Dict[str, Any]] = 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[Dict[str, Any]]`	Optional `use_ref()` dict 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[Dict[str, Any]] = 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[Dict[str, Any]]`	Optional `use_ref()` dict 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, style: StyleProp = None, ref: Optional[Dict[str, Any]] = 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`
`style`	`StyleProp`	Style dict (or list of dicts).	`None`
`ref`	`Optional[Dict[str, Any]]`	Optional `use_ref()` dict.	`None`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

SafeAreaView ¶

SafeAreaView(*children: Element, style: StyleProp = 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`	`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 `"SafeAreaView"`.

Modal ¶

Modal(*children: Element, visible: bool = False, on_dismiss: Optional[Callable[[], None]] = None, title: Optional[str] = None, animation_type: Literal['slide', 'fade', 'none'] = 'slide', transparent: bool = False, 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`
`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`
`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, pressed_opacity: float = 0.6, style: StyleProp = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None, key: Optional[str] = None) -> Element

Wrap children with tap and long-press 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`
`pressed_opacity`	`float`	Opacity (0–1) applied while the user's finger is down. Set to `1.0` for no visual feedback.	`0.6`
`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`
`key`	`Optional[str]`	Stable identity for keyed reconciliation.	`None`

Returns:

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

Fragment ¶

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

Group children without adding a wrapping native view.

Like React's <></>: returns multiple elements from a component without introducing an extra container. The reconciler flattens Fragment elements at the children-list level, so each child appears as a direct sibling of the Fragment's parent in the native tree.

Useful inside Provider / memo / conditional logic when grouping siblings inside another component's child list:

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` children are dropped, which makes conditional rendering with `cond and pn.Text(...)` ergonomic.	`()`
`key`	`Optional[str]`	Optional key for the Fragment itself (rarely useful since Fragment doesn't appear in the native tree).	`None`

Returns:

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

Note

Today, returning a Fragment from a @pn.component function only mounts its first child as the component's root. To return multiple top-level elements from a function component, use a container such as Column or Row instead.

ErrorBoundary ¶

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

Catch render errors in the wrapped subtree 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.

When multiple children are passed they're grouped under a Fragment so the boundary still wraps a single logical subtree.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Subtree to wrap.	`()`
`fallback`	`Optional[Any]`	Element rendered when the subtree 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
`Element`	`"__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, item_height: Optional[float] = None, separator_height: float = 0, refresh_control: Optional[Dict[str, Any]] = None, on_item_press: Optional[Callable[[int], None]] = None, style: StyleProp = None, key: Optional[str] = None) -> Element

Virtualized scrollable list that renders items from data lazily.

Backed by UITableView on iOS and RecyclerView on Android via the VirtualList element. Each visible row is mounted on demand by a nested Reconciler when item_height is specified.

When item_height is omitted the implementation falls back to an eager (non-virtualized) ScrollView of every row — keep the data set small in that mode (the fallback is convenient for short lists where virtualization overhead would dominate).

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`
`item_height`	`Optional[float]`	Fixed row height in layout units. Required to enable native virtualization. When omitted, the list falls back to an eager scroll of every row (not recommended for long lists).	`None`
`separator_height`	`float`	Vertical gap between items, in layout units. Combined with `item_height` for the virtualized case.	`0`
`refresh_control`	`Optional[Dict[str, Any]]`	Optional `{"refreshing": bool, "on_refresh": callable}` for pull-to-refresh; see `RefreshControl`.	`None`
`on_item_press`	`Optional[Callable[[int], None]]`	Callback invoked with the row index when the user taps a row (virtualized backend only).	`None`
`style`	`StyleProp`	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 `"VirtualList"`
`Element`	(virtualized) or `"ScrollView"` (eager fallback).

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, item_height: Optional[float] = None, section_header_height: float = 32.0, separator_height: float = 0, style: StyleProp = None, key: Optional[str] = None) -> Element

Virtualized list that supports section headers.

Internally flattens sections into a single virtualized list where each row is either a section header or a section item. The row mounter dispatches to render_section_header or render_item depending on the row's type.

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`.	`None`
`item_height`	`Optional[float]`	Fixed row height for items, in layout units.	`None`
`section_header_height`	`float`	Fixed header height in layout units.	`32.0`
`separator_height`	`float`	Gap appended below each item, in layout units.	`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` of type `"VirtualList"`
`Element`	(virtualized). When `item_height` is omitted the layout falls
`Element`	back to an eager column.

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', 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 applies it as bottom padding so the focused text input stays visible.

Parameters:

Name	Type	Description	Default
`*children`	`Element`	Children rendered inside the avoiding container.	`()`
`behavior`	`Literal['padding', 'position']`	`"padding"` (adds bottom padding) or `"position"` (translates the container upward).	`'padding'`
`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`	`"KeyboardAvoidingView"`.

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, ref: Optional[Dict[str, Any]] = 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`
`ref`	`Optional[Dict[str, Any]]`	Optional `use_ref()` dict.	`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.

Components¶

TextProps dataclass ¶

ButtonProps dataclass ¶

TextInputProps dataclass ¶

ImageProps dataclass ¶

SwitchProps dataclass ¶

ProgressBarProps dataclass ¶

ActivityIndicatorProps dataclass ¶

WebViewProps dataclass ¶

SpacerProps dataclass ¶

SliderProps dataclass ¶

ViewProps dataclass ¶

ScrollViewProps dataclass ¶

SafeAreaViewProps dataclass ¶

ModalProps dataclass ¶

PressableProps dataclass ¶

StatusBarProps dataclass ¶

KeyboardAvoidingViewProps dataclass ¶

PickerProps dataclass ¶

Text ¶

Button ¶

TextInput ¶

Image ¶

Switch ¶

ProgressBar ¶

ActivityIndicator ¶

WebView ¶

Spacer ¶

Slider ¶

View ¶

Column ¶

Row ¶

ScrollView ¶

SafeAreaView ¶

Modal ¶

Pressable ¶

Fragment ¶

ErrorBoundary ¶

FlatList ¶

SectionList ¶

StatusBar ¶

KeyboardAvoidingView ¶

RefreshControl ¶

Picker ¶

Next steps¶

TextProps `dataclass` ¶

ButtonProps `dataclass` ¶

TextInputProps `dataclass` ¶

ImageProps `dataclass` ¶

SwitchProps `dataclass` ¶

ProgressBarProps `dataclass` ¶

ActivityIndicatorProps `dataclass` ¶

WebViewProps `dataclass` ¶

SpacerProps `dataclass` ¶

SliderProps `dataclass` ¶

ViewProps `dataclass` ¶

ScrollViewProps `dataclass` ¶

SafeAreaViewProps `dataclass` ¶

ModalProps `dataclass` ¶

PressableProps `dataclass` ¶

StatusBarProps `dataclass` ¶

KeyboardAvoidingViewProps `dataclass` ¶

PickerProps `dataclass` ¶