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`.
`TouchableOpacityProps`	Props for `TouchableOpacity`.
`ImageBackgroundProps`	Props for `ImageBackground`.
`CheckboxProps`	Props for `Checkbox`.
`SegmentedControlProps`	Props for `SegmentedControl`.
`DatePickerProps`	Props for `DatePicker`.

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 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.
`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.

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, 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, 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, accessibility_label: Optional[str] = None)

Bases: Props

Props for Switch.

ProgressBarProps `dataclass` ¶

ProgressBarProps(value: float = 0.0, color: Optional[Color] = None, track_color: Optional[Color] = None, indeterminate: bool = False)

Bases: Props

Props for ProgressBar.

ActivityIndicatorProps `dataclass` ¶

ActivityIndicatorProps(animating: bool = True, color: Optional[Color] = None, size: Literal['small', 'large'] = 'small')

Bases: Props

Props for ActivityIndicator.

WebViewProps `dataclass` ¶

WebViewProps(url: Optional[str] = None, 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)

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, accessibility_label: Optional[str] = None)

Bases: Props

Props for Slider.

ViewProps `dataclass` ¶

ViewProps(gestures: Optional[List[Any]] = None, 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, 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)

Bases: Props

Props for ScrollView.

on_scroll receives a single payload dict with "x" and "y" content offsets in points.

SafeAreaViewProps `dataclass` ¶

SafeAreaViewProps()

Bases: Props

Props for SafeAreaView.

ModalProps `dataclass` ¶

ModalProps(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)

Bases: Props

Props for Modal.

PressableProps `dataclass` ¶

PressableProps(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, 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.

TouchableOpacityProps `dataclass` ¶

TouchableOpacityProps(on_press: Optional[Callable[[], None]] = None, on_long_press: Optional[Callable[[], None]] = None, active_opacity: float = 0.2, disabled: bool = False, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessibility_role: Optional[str] = None, accessible: Optional[bool] = None)

Bases: Props

Props for TouchableOpacity.

ImageBackgroundProps `dataclass` ¶

ImageBackgroundProps(source: Optional[str] = None, scale_type: Optional[ScaleType] = None, accessibility_label: Optional[str] = None, accessible: Optional[bool] = None)

Bases: Props

Props for ImageBackground.

CheckboxProps `dataclass` ¶

CheckboxProps(value: bool = False, on_change: Optional[Callable[[bool], None]] = None, label: Optional[str] = None, disabled: bool = False, color: Optional[Color] = None, accessibility_label: Optional[str] = None, accessibility_hint: Optional[str] = None, accessible: Optional[bool] = None)

Bases: Props

Props for Checkbox.

SegmentedControlProps `dataclass` ¶

SegmentedControlProps(segments: List[str] = list(), selected_index: int = 0, on_change: Optional[Callable[[int], None]] = None, enabled: bool = True, tint_color: Optional[Color] = None, accessibility_label: Optional[str] = None, accessible: Optional[bool] = None)

Bases: Props

Props for SegmentedControl.

DatePickerProps `dataclass` ¶

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

Bases: Props

Props for DatePicker.

value and the value passed 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 the schema stays JSON-serializable and platform-agnostic.

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, 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, 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`
`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`
`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, 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, 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".
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`
`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, 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[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`
`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[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, 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: 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

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`	`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`
`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 `"Pressable"`.

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, 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`
`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, 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`
`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, 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`
`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, 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`
`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, 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 (see DatePickerProps).

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`
`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 <></>: 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, 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[Dict[str, Any]] = 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.

The ref dict (from use_ref) is populated with an imperative controller: ref["scroll_to_index"](i), ref["scroll_to_offset"](pts), and ref["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[Dict[str, Any]]`	Optional `use_ref()` dict; receives the scroll controller functions.	`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[Dict[str, Any]] = 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[Dict[str, Any]]`	Optional `use_ref()` dict; receives the scroll controller functions.	`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', 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 ¶

TouchableOpacityProps dataclass ¶

ImageBackgroundProps dataclass ¶

CheckboxProps dataclass ¶

SegmentedControlProps dataclass ¶

DatePickerProps dataclass ¶

Text ¶

Button ¶

TextInput ¶

Image ¶

Switch ¶

ProgressBar ¶

ActivityIndicator ¶

WebView ¶

Spacer ¶

Slider ¶

View ¶

Column ¶

Row ¶

ScrollView ¶

SafeAreaView ¶

Modal ¶

Pressable ¶

TouchableOpacity ¶

ImageBackground ¶

Checkbox ¶

SegmentedControl ¶

DatePicker ¶

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` ¶

TouchableOpacityProps `dataclass` ¶

ImageBackgroundProps `dataclass` ¶

CheckboxProps `dataclass` ¶

SegmentedControlProps `dataclass` ¶

DatePickerProps `dataclass` ¶