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 and long-press 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 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, 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)

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)

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, on_scroll: Optional[Callable[[float, 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.

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

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, 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, 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, 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, on_scroll: Optional[Callable[[float, 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[[float, 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, 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"`.

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, separator_height: float = 0, refresh_control: Optional[Dict[str, Any]] = None, on_item_press: Optional[Callable[[int], None]] = 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, content_container_style: StyleProp = 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`
`horizontal`	`bool`	Lay rows out left-to-right instead of top-to-bottom (forces the eager backend).	`False`
`num_columns`	`int`	Render items in a grid of this many columns (forces the eager backend). `1` (default) is a plain list.	`1`
`list_header`	`Optional[Element]`	Optional element rendered once above all rows.	`None`
`list_footer`	`Optional[Element]`	Optional element rendered once below all rows.	`None`
`list_empty`	`Optional[Element]`	Optional element rendered when `data` is empty.	`None`
`on_end_reached`	`Optional[Callable[[], None]]`	Callback invoked when the user scrolls within `on_end_reached_threshold` of the end (virtualized backend).	`None`
`on_end_reached_threshold`	`float`	Fraction of the viewport from the end at which `on_end_reached` fires.	`0.5`
`content_container_style`	`StyleProp`	Style applied to the inner content wrapper (forces the eager backend).	`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 ¶

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