Components

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

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

Built-in element factories.

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

The factories are grouped by concern into submodules (text, media, controls, layout, pressable, overlays, structural, lists); everything public is re-exported here, so from pythonnative.components import Text keeps working.

Example

import pythonnative as pn

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

Modules:

Name	Description
controls	Form controls and side-effect elements.
graphics	Graphics factories: Svg, LinearGradient, and BlurView.
layout	Container factories: View, Column, Row, Spacer, ScrollView, and the inset-aware wrappers.
lists	Keyed virtualized lists with one logical component tree.
media	Media factories: Image, ImageBackground, and WebView.
media_events	Typed media events shared by Python, iOS, Android, and preview.
overlays	Overlay factories: Modal (native presentation) and Portal (window overlay).
pressable	Touch wrappers: Pressable and its TouchableOpacity alias.
structural	Structural factories: Fragment, ErrorBoundary, and Suspense.
text	Text-centric leaf factories: Text, Button, and TextInput.

Classes:

Name	Description
ListController	Imperative scroll handle published on a list's ref.
ImageLoadEvent	Decoded image dimensions in the platform's logical display units.
WebNavigationEvent	The top-level document's navigation state at a load transition.

Functions:

Name	Description
ActivityIndicator	Show an indeterminate loading spinner.
Checkbox	A boolean checkbox with an optional inline label.
DatePicker	A native date / time picker.
Picker	A real native dropdown / select widget.
ProgressBar	Show determinate progress as a value between 0.0 and 1.0.
RefreshControl	Pull-to-refresh control for ScrollView and the list components.
SegmentedControl	A horizontal multi-choice control (one selected segment at a time).
Slider	Continuous-value slider between min_value and max_value.
StatusBar	Configure the device's status bar appearance.
Switch	Display a toggle switch.
BlurView	A container that blurs whatever is drawn behind it.
LinearGradient	A container filled with a linear color gradient.
Svg	Draw vector shapes in a single native view.
Column	Arrange children vertically.
KeyboardAvoidingView	Wrap content that should shift up when the keyboard is shown.
Row	Arrange children horizontally.
SafeAreaView	Container that respects safe-area insets (notch, status bar, home indicator).
ScrollView	Wrap children in a scrollable container.
Spacer	Insert empty space inside a flex container.
View	Universal flex container (like React Native's View).
FlatList	Virtualized scrollable list that renders items from data lazily.
SectionList	Virtualized list with section headers interleaved between row groups.
Image	Display a bundled, local, or remote image.
ImageBackground	Render children layered on top of a background image.
WebView	Embed web content from a URL or an inline HTML string.
Modal	Overlay modal dialog backed by a real native presentation.
Portal	Render children into a full-screen overlay above everything else.
Pressable	Wrap children with tap / long-press / gesture handlers.
TouchableOpacity	Wrap children so they fade to active_opacity while pressed.
ErrorBoundary	Catch render errors in the wrapped subtree and display fallback instead.
Fragment	Group children without adding a wrapping native view.
Suspense	Show fallback while descendants wait on async work, then swap in the content.
Button	Display a tappable button.
Text	Display a string of text, optionally with styled nested spans.
TextInput	Display a text-entry field (single-line by default, or multiline).

Attributes:

Name	Type	Description
BlurType		Backdrop material styles for BlurView.
PreserveAspectRatio		How an Svg view box scales into a frame of a different aspect ratio.
ImageSource		What Image.source accepts: a URL, data: URI, file path, or bundled Asset.

BlurType module-attribute

BlurType = Literal[
    "light",
    "dark",
    "regular",
    "prominent",
    "extra_light",
    "system_thin_material",
    "system_material",
    "system_thick_material",
    "system_chrome_material",
]

Backdrop material styles for BlurView.

PreserveAspectRatio module-attribute

PreserveAspectRatio = Literal['meet', 'slice', 'none']

How an Svg view box scales into a frame of a different aspect ratio.

ImageSource module-attribute

ImageSource = Union[str, Asset]

What Image.source accepts: a URL, data: URI, file path, or bundled Asset.

ListController

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

Imperative scroll handle published on a list's ref.

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

Example

import pythonnative as pn

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

Methods:

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

scroll_to_offset

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

Scroll to an absolute content offset in points.

scroll_to_index

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

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

scroll_to_end

scroll_to_end(animated: bool = True) -> None

Scroll to the end of the content.

ImageLoadEvent dataclass

ImageLoadEvent(width: float, height: float)

Decoded image dimensions in the platform's logical display units.

WebNavigationEvent dataclass

WebNavigationEvent(
    url: str,
    loading: bool,
    can_go_back: bool,
    can_go_forward: bool,
    title: str = "",
)

The top-level document's navigation state at a load transition.

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

Checkbox

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

A boolean checkbox with an optional inline label.

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

Parameters:

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

Returns:

Type	Description
Element	An Element of type "Checkbox".

DatePicker

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

A native date / time picker.

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

Parameters:

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

Returns:

Type	Description
Element	An Element of type "DatePicker".

Picker

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

A real native dropdown / select widget.

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

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

Parameters:

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

Returns:

Type	Description
Element	An Element of type "Picker".

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

RefreshControl

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

Pull-to-refresh control for ScrollView and the list components.

Pass the result as the refresh_control= prop of a ScrollView, FlatList, or SectionList. It is a regular Element (type "RefreshControl") built like every other piece of UI; the scroll container attaches it to its native scroll view rather than rendering it as a child, and rejects anything else with a TypeError.

Parameters:

Name	Type	Description	Default
refreshing	bool	Drive the spinner's visibility from a use_state value.	False
on_refresh	Optional[Callable[[], Any]]	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
Element	An Element of type "RefreshControl".

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

SegmentedControl

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

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

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

Parameters:

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

Returns:

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

Slider

Slider(
    *,
    value: float = 0.0,
    min_value: float = 0.0,
    max_value: float = 1.0,
    on_change: Optional[Callable[[float], Any]] = None,
    disabled: bool = False,
    step: float = 0.0,
    minimum_track_color: Optional[Color] = None,
    maximum_track_color: Optional[Color] = None,
    thumb_color: Optional[Color] = None,
    on_sliding_start: Optional[
        Callable[[float], Any]
    ] = None,
    on_sliding_complete: Optional[
        Callable[[float], Any]
    ] = 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], Any]]	Callback invoked with the new value as the user drags.	None
disabled	bool	Prevent dragging the slider.	False
step	float	Snap values to this increment, or zero for continuous movement.	0.0
minimum_track_color	Optional[Color]	Filled track color.	None
maximum_track_color	Optional[Color]	Unfilled track color.	None
thumb_color	Optional[Color]	Thumb color, or the platform default.	None
on_sliding_start	Optional[Callable[[float], Any]]	Callback when the user starts dragging.	None
on_sliding_complete	Optional[Callable[[float], Any]]	Callback when the user finishes dragging.	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".

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

Switch

Switch(
    *,
    value: bool = False,
    on_change: Optional[Callable[[bool], Any]] = None,
    disabled: bool = False,
    on_tint_color: Optional[Color] = None,
    thumb_color: Optional[Color] = 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], Any]]	Callback invoked with the new boolean state.	None
disabled	bool	Prevent changes while keeping the switch visible.	False
on_tint_color	Optional[Color]	Track color when the switch is on.	None
thumb_color	Optional[Color]	Thumb color, or the platform default.	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".

BlurView

BlurView(
    *children: Element,
    blur_type: BlurType = "regular",
    intensity: float = 100.0,
    style: StyleProp = None,
    accessibility_label: Optional[str] = None,
    accessible: Optional[bool] = None,
    test_id: Optional[str] = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

A container that blurs whatever is drawn behind it.

On iOS this is a UIVisualEffectView (blur_type selects the UIBlurEffect style). In the browser preview it is backdrop-filter. Android has no system backdrop blur, so the view snapshots the content beneath it at reduced resolution, blurs the snapshot, and tints it; it looks right for static backgrounds and approximates animated ones.

Parameters:

Name	Type	Description	Default
*children	Element	Content drawn over the blur.	()
blur_type	BlurType	The material style. "light", "dark", and "regular" are portable; the system_* values map to the iOS 13 materials and fall back to the closest tint elsewhere.	'regular'
intensity	float	Blur strength from 0 (transparent) to 100.	100.0
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
test_id	Optional[str]	Stable identifier for UI tests.	None
ref	Optional[Ref]	Optional Ref from use_ref().	None
key	Optional[str]	Stable identity for keyed reconciliation.	None

Returns:

Type	Description
Element	An Element of type "BlurView".

Example

pn.ImageBackground(
    pn.BlurView(pn.Text("Caption"), blur_type="dark", style=pn.style(padding=12)),
    source=pn.asset("images/hero.jpg"),
    style=pn.style(height=200, justify_content="flex-end"),
)

LinearGradient

LinearGradient(
    *children: Element,
    colors: Sequence[Color],
    locations: Optional[Sequence[float]] = None,
    start_point: Tuple[float, float] = (0.0, 0.0),
    end_point: Tuple[float, float] = (0.0, 1.0),
    style: StyleProp = None,
    accessibility_label: Optional[str] = None,
    accessible: Optional[bool] = None,
    test_id: Optional[str] = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

A container filled with a linear color gradient.

Lays out children exactly like View; the gradient is the background. start_point and end_point are unit coordinates in the view's box ((0, 0) top-left, (1, 1) bottom-right), so the defaults draw top to bottom.

Parameters:

Name	Type	Description	Default
*children	Element	Content drawn over the gradient.	()
colors	Sequence[Color]	Two or more colors, in order from start_point to end_point.	required
locations	Optional[Sequence[float]]	Optional stop positions in [0, 1], one per color. Evenly spaced when omitted.	None
start_point	Tuple[float, float]	Unit point where the first color sits.	(0.0, 0.0)
end_point	Tuple[float, float]	Unit point where the last color sits.	(0.0, 1.0)
style	StyleProp	Style dict (or list of dicts); border_radius clips the gradient.	None
accessibility_label	Optional[str]	Spoken description for screen readers.	None
accessible	Optional[bool]	Override whether the element is exposed to AT.	None
test_id	Optional[str]	Stable identifier for UI tests.	None
ref	Optional[Ref]	Optional Ref from use_ref().	None
key	Optional[str]	Stable identity for keyed reconciliation.	None

Returns:

Type	Description
Element	An Element of type "LinearGradient".

Raises:

Type	Description
ValueError	If fewer than two colors are given or locations doesn't match colors in length.

Example

pn.LinearGradient(
    pn.Text("Welcome", style=pn.style(color="white", font_size=24)),
    colors=["#6366F1", "#EC4899"],
    start_point=(0, 0),
    end_point=(1, 1),
    style=pn.style(padding=24, border_radius=16),
)

Svg

Svg(
    *children: Any,
    shapes: Optional[Sequence[SvgShape]] = None,
    view_box: Optional[str] = None,
    preserve_aspect_ratio: PreserveAspectRatio = "meet",
    fill: Optional[Color] = None,
    stroke: Optional[Color] = None,
    stroke_width: Optional[float] = None,
    stroke_linecap: Optional[LineCap] = None,
    stroke_linejoin: Optional[LineJoin] = None,
    fill_rule: Optional[FillRule] = None,
    style: StyleProp = None,
    accessibility_label: Optional[str] = None,
    accessibility_role: Optional[str] = None,
    accessible: Optional[bool] = None,
    accessibility_state: Optional[
        AccessibilityState
    ] = None,
    test_id: Optional[str] = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

Draw vector shapes in a single native view.

Pass shapes from pythonnative.svg (Path, Circle, Rect, Line, Polyline, Polygon, Ellipse, and G groups) as children. Coordinates are in view_box units and are scaled into the view's frame. Without an explicit width and height in style, the view measures to the view box size.

Paint left unset on a shape inherits the root values here, then the SVG defaults (black fill, no stroke). Set fill="none" to draw outlines only.

Parameters:

Name	Type	Description	Default
*children	Any	Shapes and groups to draw, in paint order.	()
shapes	Optional[Sequence[SvgShape]]	Pre-flattened shape records (what pn.svg.load produces). Combined with children.	None
view_box	Optional[str]	"min-x min-y width height". Defaults to "0 0 24 24".	None
preserve_aspect_ratio	PreserveAspectRatio	"meet" letterboxes, "slice" crops, "none" stretches.	'meet'
fill	Optional[Color]	Default fill color for shapes that don't set one.	None
stroke	Optional[Color]	Default stroke color.	None
stroke_width	Optional[float]	Default stroke width in view box units.	None
stroke_linecap	Optional[LineCap]	Default line cap.	None
stroke_linejoin	Optional[LineJoin]	Default line join.	None
fill_rule	Optional[FillRule]	Default fill rule.	None
style	StyleProp	Style dict (or list of dicts). width and height set the drawn size; opacity and transforms apply as usual.	None
accessibility_label	Optional[str]	Spoken description for screen readers.	None
accessibility_role	Optional[str]	Override the default "image" role.	None
accessible	Optional[bool]	Override whether the element is exposed to AT.	None
accessibility_state	Optional[AccessibilityState]	Current widget state for assistive tech.	None
test_id	Optional[str]	Stable identifier for UI tests.	None
ref	Optional[Ref]	Optional Ref from use_ref().	None
key	Optional[str]	Stable identity for keyed reconciliation.	None

Returns:

Type	Description
Element	An Element of type "Svg".

Example

from pythonnative import svg

pn.Svg(
    svg.Circle(cx=12, cy=12, r=10, fill="#0EA5E9"),
    svg.Path(d="M8 12h8", stroke="white", stroke_width=2),
    view_box="0 0 24 24",
    style=pn.style(width=48, height=48),
)

Column

Column(
    *children: Element,
    style: StyleProp = None,
    gestures: Optional[List[Any]] = None,
    hit_slop: Optional[
        Union[float, Dict[str, float]]
    ] = None,
    on_layout: Optional[
        Callable[[Dict[str, float]], None]
    ] = None,
    accessibility_label: Optional[str] = None,
    accessibility_hint: Optional[str] = None,
    accessibility_role: Optional[str] = None,
    accessible: Optional[bool] = None,
    accessibility_state: Optional[
        AccessibilityState
    ] = None,
    accessibility_live_region: Optional[
        Literal["none", "polite", "assertive"]
    ] = None,
    test_id: Optional[str] = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

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.

Accepts every View prop (gestures, hit slop, accessibility, test_id); only flex_direction is fixed.

Parameters:

Name	Type	Description	Default
*children	Element	Child elements stacked top to bottom.	()
style	StyleProp	Style dict (or list of dicts).	None
gestures	Optional[List[Any]]	Gesture descriptors recognized natively on this view.	None
hit_slop	Optional[Union[float, Dict[str, float]]]	Extra touch target beyond the bounds (see View).	None
on_layout	Optional[Callable[[Dict[str, float]], None]]	Callback invoked with {"x", "y", "width", "height"} after layout and on frame changes.	None
accessibility_label	Optional[str]	Spoken description for screen readers.	None
accessibility_hint	Optional[str]	Spoken extra detail (iOS only).	None
accessibility_role	Optional[str]	Semantic role for assistive tech.	None
accessible	Optional[bool]	Override whether the element is exposed to AT.	None
accessibility_state	Optional[AccessibilityState]	Current widget state for assistive tech.	None
accessibility_live_region	Optional[Literal['none', 'polite', 'assertive']]	How AT announces dynamic changes (Android only).	None
test_id	Optional[str]	Stable identifier for UI tests.	None
ref	Optional[Ref]	Optional Ref for native-view access.	None
key	Optional[str]	Stable identity for keyed reconciliation.	None

Returns:

Type	Description
Element	An Element of type "Column".

KeyboardAvoidingView

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

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

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

Parameters:

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

Returns:

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

Row

Row(
    *children: Element,
    style: StyleProp = None,
    gestures: Optional[List[Any]] = None,
    hit_slop: Optional[
        Union[float, Dict[str, float]]
    ] = None,
    on_layout: Optional[
        Callable[[Dict[str, float]], None]
    ] = None,
    accessibility_label: Optional[str] = None,
    accessibility_hint: Optional[str] = None,
    accessibility_role: Optional[str] = None,
    accessible: Optional[bool] = None,
    accessibility_state: Optional[
        AccessibilityState
    ] = None,
    accessibility_live_region: Optional[
        Literal["none", "polite", "assertive"]
    ] = None,
    test_id: Optional[str] = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

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.

Accepts every View prop (gestures, hit slop, accessibility, test_id); only flex_direction is fixed.

Parameters:

Name	Type	Description	Default
*children	Element	Child elements arranged left to right.	()
style	StyleProp	Style dict (or list of dicts).	None
gestures	Optional[List[Any]]	Gesture descriptors recognized natively on this view.	None
hit_slop	Optional[Union[float, Dict[str, float]]]	Extra touch target beyond the bounds (see View).	None
on_layout	Optional[Callable[[Dict[str, float]], None]]	Callback invoked with {"x", "y", "width", "height"} after layout and on frame changes.	None
accessibility_label	Optional[str]	Spoken description for screen readers.	None
accessibility_hint	Optional[str]	Spoken extra detail (iOS only).	None
accessibility_role	Optional[str]	Semantic role for assistive tech.	None
accessible	Optional[bool]	Override whether the element is exposed to AT.	None
accessibility_state	Optional[AccessibilityState]	Current widget state for assistive tech.	None
accessibility_live_region	Optional[Literal['none', 'polite', 'assertive']]	How AT announces dynamic changes (Android only).	None
test_id	Optional[str]	Stable identifier for UI tests.	None
ref	Optional[Ref]	Optional Ref for native-view access.	None
key	Optional[str]	Stable identity for keyed reconciliation.	None

Returns:

Type	Description
Element	An Element of type "Row".

SafeAreaView

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

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

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

Parameters:

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

Returns:

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

ScrollView

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

Wrap children in a scrollable container.

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

Parameters:

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

Returns:

Type	Description
Element	An Element of type "ScrollView".

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

View

View(
    *children: Element,
    style: StyleProp = None,
    gestures: Optional[List[Any]] = None,
    hit_slop: Optional[
        Union[float, Dict[str, float]]
    ] = None,
    on_layout: Optional[
        Callable[[Dict[str, float]], None]
    ] = None,
    accessibility_label: Optional[str] = None,
    accessibility_hint: Optional[str] = None,
    accessibility_role: Optional[str] = None,
    accessible: Optional[bool] = None,
    accessibility_state: Optional[
        AccessibilityState
    ] = None,
    accessibility_live_region: Optional[
        Literal["none", "polite", "assertive"]
    ] = None,
    test_id: Optional[str] = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

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

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

Flex container properties (passed via style):

• flex_direction: "column" (default), "row", "column_reverse", "row_reverse".
• flex_wrap: "nowrap" (default), "wrap", "wrap_reverse", with align_content controlling how wrapped lines share leftover cross-axis space.
• justify_content: main-axis distribution. Accepts "flex_start" (default), "center", "flex_end", "space_between", "space_around", "space_evenly".
• align_items: cross-axis alignment. Accepts "stretch" (default), "flex_start", "center", "flex_end".
• direction: "ltr" (default) or "rtl". Flips rows and resolves margin_start / padding_end / absolute start / end insets.
• overflow: "visible" (default) or "hidden".
• spacing (alias gap; per-axis row_gap / column_gap), padding, background_color, border_radius, border_width, border_color, shadow_color, shadow_offset, shadow_opacity, shadow_radius, elevation, opacity, transform.

Parameters:

Name	Type	Description	Default
*children	Element	Child elements rendered inside the container.	()
style	StyleProp	Style dict (or list of dicts).	None
gestures	Optional[List[Any]]	Optional list of gesture descriptors from pythonnative.gestures (e.g. [gestures.Pan(on_change=…)]) recognized natively on this view.	None
hit_slop	Optional[Union[float, Dict[str, float]]]	Extend the touch target beyond the view's bounds without changing layout: a uniform number of points, or a dict with any of top / left / bottom / right.	None
on_layout	Optional[Callable[[Dict[str, float]], None]]	Callback invoked with {"x", "y", "width", "height"} after this view is laid out, and again whenever its frame changes.	None
accessibility_label	Optional[str]	Spoken description for screen readers.	None
accessibility_hint	Optional[str]	Spoken extra detail (iOS only).	None
accessibility_role	Optional[str]	Semantic role for assistive tech.	None
accessible	Optional[bool]	Override whether the element is exposed to AT.	None
accessibility_state	Optional[AccessibilityState]	Current widget state for assistive tech, e.g. {"disabled": True, "selected": False}. Recognized keys: disabled, selected, checked, busy, expanded.	None
accessibility_live_region	Optional[Literal['none', 'polite', 'assertive']]	How AT announces dynamic changes to this view: "none", "polite", or "assertive" (Android only).	None
test_id	Optional[str]	Stable identifier for UI tests; exposed as resource-id on Android and accessibilityIdentifier on iOS.	None
ref	Optional[Ref]	Optional Ref from use_ref().	None
key	Optional[str]	Stable identity for keyed reconciliation.	None

Returns:

Type	Description
Element	An Element of type "View".

FlatList

FlatList(
    *,
    data: Optional[Sequence[Any]] = None,
    data_revision: int = 0,
    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[Element] = 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[[], Any]] = None,
    on_end_reached_threshold: float = 0.5,
    on_viewable_items_changed: Optional[
        Callable[[List[Dict[str, Any]]], None]
    ] = None,
    on_scroll: Optional[
        Callable[[Dict[str, float]], None]
    ] = None,
    shows_scroll_indicator: bool = True,
    content_container_style: StyleProp = None,
    style: StyleProp = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

Virtualized scrollable list that renders items from data lazily.

A bounded window of keyed row components supplies content to the renderer. UIKit collection views and Android recycler views own native cells; the browser implements the same row-request protocol. Headless backends simulate the same row requests. Rows may have variable heights: pass item_height when rows are uniform, get_item_height for exact per-item extents, or nothing at all; unknown rows start at estimated_item_height and are corrected with their measured extent once they've been on screen.

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

Parameters:

Name	Type	Description	Default
data	Optional[Sequence[Any]]	Sequence of arbitrary item values. Replace the sequence when it changes.	None
data_revision	int	Increment after changing a sequence in place. Unchanged sequence identity and revision reuse the indexed dataset.	0
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[Element]	Optional RefreshControl element for pull-to-refresh.	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[[], Any]]	Called when the user scrolls within on_end_reached_threshold viewports of the end (fires once per dataset revision).	None
on_end_reached_threshold	float	Distance from the end, in viewport multiples, at which on_end_reached fires.	0.5
on_viewable_items_changed	Optional[Callable[[List[Dict[str, Any]]], None]]	Called with a list of {"index", "key", "item"} dicts whenever the set of visible rows changes.	None
on_scroll	Optional[Callable[[Dict[str, float]], None]]	Called with the raw scroll payload ({"x": …, "y": …}).	None
shows_scroll_indicator	bool	When False, hides the scroll bar.	True
content_container_style	StyleProp	Style applied to the inner content wrapper.	None
style	StyleProp	Style for the outer scroll container.	None
ref	Optional[Ref]	Optional Ref; receives a ListController on ref.current after mount.	None
key	Optional[str]	Stable identity for keyed reconciliation of the list.	None

Returns:

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

Example

import pythonnative as pn

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

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

SectionList

SectionList(
    *,
    sections: Optional[Sequence[Dict[str, Any]]] = None,
    data_revision: int = 0,
    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[Element] = None,
    list_header: Optional[Element] = None,
    list_footer: Optional[Element] = None,
    list_empty: Optional[Element] = None,
    on_end_reached: Optional[Callable[[], Any]] = None,
    on_end_reached_threshold: float = 0.5,
    on_scroll: Optional[
        Callable[[Dict[str, float]], None]
    ] = None,
    style: StyleProp = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

Virtualized list with section headers interleaved between row groups.

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

Parameters:

Name	Type	Description	Default
data_revision	int	Increment after changing sections in place to rebuild the indexed dataset.	0
sections	Optional[Sequence[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[Element]	Optional RefreshControl element.	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[[], Any]]	Called near the end of the content.	None
on_end_reached_threshold	float	Distance from the end, in viewport multiples, at which on_end_reached fires.	0.5
on_scroll	Optional[Callable[[Dict[str, float]], None]]	Called with the raw scroll payload.	None
style	StyleProp	Style for the outer scroll container.	None
ref	Optional[Ref]	Optional Ref; receives a ListController on ref.current after mount.	None
key	Optional[str]	Stable identity for keyed reconciliation of the list.	None

Returns:

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

Image

Image(
    source: ImageSource = "",
    *,
    default_source: Optional[ImageSource] = None,
    scale_type: Optional[ScaleType] = None,
    tint_color: Optional[Color] = None,
    placeholder_color: Optional[Color] = None,
    blur_radius: Optional[float] = None,
    on_load: Optional[
        Callable[[ImageLoadEvent], Any]
    ] = None,
    on_error: Optional[Callable[[str], Any]] = None,
    style: StyleProp = None,
    accessibility_label: Optional[str] = None,
    accessibility_role: Optional[str] = None,
    accessible: Optional[bool] = None,
    accessibility_state: Optional[
        AccessibilityState
    ] = None,
    accessibility_live_region: Optional[
        Literal["none", "polite", "assertive"]
    ] = None,
    test_id: Optional[str] = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

Display a bundled, local, or remote image.

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

Bundled images live under app/assets/ and are referenced with pn.asset; density variants (logo@2x.png, logo@3x.png) are picked for the device automatically and the image measures at its logical (1x) size.

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

Parameters:

Name	Type	Description	Default
source	ImageSource	A bundled Asset, an http(s) URL, a data: URI, or an absolute file path.	''
default_source	Optional[ImageSource]	A bundled or local image shown until source has loaded (and left in place if it fails). Must not be a network URL.	None
scale_type	Optional[ScaleType]	Fit mode: "cover", "contain", "stretch", "center".	None
tint_color	Optional[Color]	Color overlay applied to template images (monochrome icons).	None
placeholder_color	Optional[Color]	Background color shown while a remote image is loading (and left in place if it fails).	None
blur_radius	Optional[float]	Gaussian blur radius in logical points applied to the decoded image.	None
on_load	Optional[Callable[[ImageLoadEvent], Any]]	Callback invoked once the image has been decoded and displayed, with its logical width and height.	None
on_error	Optional[Callable[[str], Any]]	Callback invoked with an error message when a remote image fails to download or decode.	None
style	StyleProp	Style dict (or list of dicts).	None
accessibility_label	Optional[str]	Spoken description for screen readers.	None
accessibility_role	Optional[str]	Override the default "image" role.	None
accessible	Optional[bool]	Override whether the element is exposed to AT.	None
accessibility_state	Optional[AccessibilityState]	Current widget state for assistive tech, e.g. {"disabled": True, "selected": False}. Recognized keys: disabled, selected, checked, busy, expanded.	None
accessibility_live_region	Optional[Literal['none', 'polite', 'assertive']]	How AT announces dynamic changes to this view: "none", "polite", or "assertive" (Android only).	None
test_id	Optional[str]	Stable identifier for UI tests; exposed as resource-id on Android and accessibilityIdentifier on iOS.	None
ref	Optional[Ref]	Optional Ref from use_ref().	None
key	Optional[str]	Stable identity for keyed reconciliation.	None

Returns:

Type	Description
Element	An Element of type "Image".

ImageBackground

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

Render children layered on top of a background image.

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

Parameters:

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

Returns:

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

WebView

WebView(
    *,
    url: str = "",
    html: Optional[str] = None,
    on_load: Optional[Callable[[str], Any]] = None,
    on_load_start: Optional[Callable[[str], Any]] = None,
    on_error: Optional[Callable[[str], Any]] = None,
    on_message: Optional[Callable[[str], Any]] = None,
    on_navigation_state_change: Optional[
        Callable[[WebNavigationEvent], Any]
    ] = 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], Any]]	Callback invoked with the final URL once a page finishes loading.	None
on_load_start	Optional[Callable[[str], Any]]	Callback invoked with the URL when loading starts.	None
on_error	Optional[Callable[[str], Any]]	Callback invoked with a top-level load error message.	None
on_message	Optional[Callable[[str], Any]]	Callback invoked with the string payload whenever page JavaScript calls window.pythonnative.postMessage(...).	None
on_navigation_state_change	Optional[Callable[[WebNavigationEvent], Any]]	Callback invoked with a typed navigation state when the top-level document starts or finishes loading.	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".

Modal

Modal(
    *children: Element,
    visible: bool = False,
    on_dismiss: Optional[Callable[[], Any]] = None,
    on_show: Optional[Callable[[], Any]] = 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[[], Any]]	Callback invoked when the user dismisses the modal via system gesture.	None
on_show	Optional[Callable[[], Any]]	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".

Portal

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

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

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

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

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

Parameters:

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

Returns:

Type	Description
Element	An Element of type "Portal".

Pressable

Pressable(
    *children: Element,
    on_press: Optional[Callable[[], Any]] = None,
    on_long_press: Optional[Callable[[], Any]] = None,
    on_press_in: Optional[Callable[[], Any]] = None,
    on_press_out: Optional[Callable[[], Any]] = None,
    pressed_opacity: float = 0.6,
    gestures: Optional[List[Any]] = None,
    hit_slop: Optional[
        Union[float, Dict[str, float]]
    ] = None,
    on_layout: Optional[
        Callable[[Dict[str, float]], None]
    ] = None,
    style: Union[
        StyleProp, Callable[[Dict[str, bool]], StyleProp]
    ] = None,
    accessibility_label: Optional[str] = None,
    accessibility_hint: Optional[str] = None,
    accessibility_role: Optional[str] = None,
    accessible: Optional[bool] = None,
    accessibility_state: Optional[
        AccessibilityState
    ] = None,
    accessibility_live_region: Optional[
        Literal["none", "polite", "assertive"]
    ] = None,
    test_id: Optional[str] = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

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

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

Pressable gets accessibility_role="button" by default.

Parameters:

Name	Type	Description	Default
*children	Element	Elements to make pressable.	()
on_press	Optional[Callable[[], Any]]	Callback invoked on a normal tap.	None
on_long_press	Optional[Callable[[], Any]]	Callback invoked on a sustained press.	None
on_press_in	Optional[Callable[[], Any]]	Callback invoked the moment the press starts.	None
on_press_out	Optional[Callable[[], Any]]	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
hit_slop	Optional[Union[float, Dict[str, float]]]	Extend the touch target beyond the view's bounds without changing layout: a uniform number of points, or a dict with any of top / left / bottom / right. Essential for small touch targets (icons, chips) that should honor the 44-point guideline.	None
on_layout	Optional[Callable[[Dict[str, float]], None]]	Callback invoked with {"x", "y", "width", "height"} after layout and on frame changes.	None
style	Union[StyleProp, Callable[[Dict[str, bool]], StyleProp]]	Style dict applied to the wrapper, or a callable receiving the interaction state ({"pressed": bool}) and returning a style, re-evaluated on every press transition: pn.Pressable( pn.Text("Tap"), style=lambda s: pn.style( background_color="#0051A8" if s["pressed"] else "#007AFF", ), )	None
accessibility_label	Optional[str]	Spoken description for screen readers.	None
accessibility_hint	Optional[str]	Spoken extra detail (iOS only).	None
accessibility_role	Optional[str]	Override the default "button" role.	None
accessible	Optional[bool]	Override whether the element is exposed to AT.	None
accessibility_state	Optional[AccessibilityState]	Current widget state for assistive tech, e.g. {"disabled": True, "selected": False}. Recognized keys: disabled, selected, checked, busy, expanded.	None
accessibility_live_region	Optional[Literal['none', 'polite', 'assertive']]	How AT announces dynamic changes to this view: "none", "polite", or "assertive" (Android only).	None
test_id	Optional[str]	Stable identifier for UI tests; exposed as resource-id on Android and accessibilityIdentifier on iOS.	None
ref	Optional[Ref]	Optional Ref from use_ref().	None
key	Optional[str]	Stable identity for keyed reconciliation.	None

Returns:

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

TouchableOpacity

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

Wrap children so they fade to active_opacity while pressed.

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

Parameters:

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

Returns:

Type	Description
Element	An Element of type "Pressable".

ErrorBoundary

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

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

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

fallback may be:

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

Parameters:

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

Returns:

Type	Description
Element	An Element whose type is
Element	ERROR_BOUNDARY, with
Element	fallback and on_error in its props (omitted when
Element	None).

Example

import pythonnative as pn

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

Fragment

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

Group children without adding a wrapping native view.

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

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

Parameters:

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

Returns:

Type	Description
Element	An Element whose type is
Element	FRAGMENT.

Suspense

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

Show fallback while descendants wait on async work, then swap in the content.

A Suspense boundary catches suspensions from the subtree it wraps: an async def component body blocking on a pending await, or a regular component calling Resource.read on data that hasn't arrived (see use_resource and lazy). While anything is pending the boundary renders fallback; when the awaited work completes it retries the content and swaps it in. Suspended components keep their hook state across retries, so cached resources aren't refetched.

Two timing behaviors, matching React:

• Initial mount: the fallback shows until the content is ready.
• Updates: a component that's already on screen and suspends again (its dependencies changed) keeps its previous content visible and re-renders when ready; there's no fallback flash.

Parameters:

Name	Type	Description	Default
*children	Element	Subtree to wrap (the async content).	()
fallback	Optional[Any]	Content shown while suspended: an Element or a zero-arg callable returning one. Without it, suspensions propagate to the next Suspense boundary up.	None
key	Optional[str]	Stable identity for keyed reconciliation.	None

Returns:

Type	Description
Element	An Element whose type is
Element	SUSPENSE, with fallback
Element	in its props.

Example

import pythonnative as pn

@pn.component
async def Profile(user_id: str):
    user = await api.fetch_user(user_id)
    return pn.Text(user.name)

@pn.component
def Screen():
    return pn.Suspense(
        Profile(user_id="42"),
        fallback=pn.ActivityIndicator(),
    )

Button

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

Display a tappable button.

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

Buttons get accessibility_role="button" by default.

Parameters:

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

Returns:

Type	Description
Element	An Element of type "Button".

Text

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

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

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

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

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

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

Parameters:

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

Returns:

Type	Description
Element	An Element of type "Text".

TextInput

TextInput(
    *,
    value: str = "",
    placeholder: Optional[str] = None,
    on_change: Optional[Callable[[str], Any]] = None,
    on_selection_change: Optional[
        Callable[[Dict[str, int]], Any]
    ] = None,
    on_submit: Optional[Callable[[str], Any]] = 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[[], Any]] = None,
    on_blur: Optional[Callable[[], Any]] = None,
    selection_color: Optional[Color] = None,
    text_content_type: Optional[str] = None,
    style: StyleProp = None,
    accessibility_label: Optional[str] = None,
    accessibility_hint: Optional[str] = None,
    accessible: Optional[bool] = None,
    accessibility_state: Optional[
        AccessibilityState
    ] = None,
    accessibility_live_region: Optional[
        Literal["none", "polite", "assertive"]
    ] = None,
    test_id: Optional[str] = None,
    ref: Optional[Ref] = None,
    key: Optional[str] = None
) -> Element

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

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

Parameters:

Name	Type	Description	Default
value	str	Current text content (controlled-input pattern).	''
placeholder	Optional[str]	Hint shown when value is empty.	None
on_change	Optional[Callable[[str], Any]]	Callback invoked with the new string each keystroke.	None
on_selection_change	Optional[Callable[[Dict[str, int]], Any]]	Receives {"start": int, "end": int} UTF-16 offsets.	None
on_submit	Optional[Callable[[str], Any]]	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[[], Any]]	Callback invoked when the field gains focus.	None
on_blur	Optional[Callable[[], Any]]	Callback invoked when the field loses focus.	None
selection_color	Optional[Color]	Cursor / selection highlight color.	None
text_content_type	Optional[str]	Semantic content hint for autofill (e.g. "username", "password", "one_time_code").	None
style	StyleProp	Style dict (or list of dicts).	None
accessibility_label	Optional[str]	Spoken description for screen readers.	None
accessibility_hint	Optional[str]	Spoken extra detail (iOS only).	None
accessible	Optional[bool]	Override whether the element is exposed to AT.	None
accessibility_state	Optional[AccessibilityState]	Current widget state for assistive tech, e.g. {"disabled": True, "selected": False}. Recognized keys: disabled, selected, checked, busy, expanded.	None
accessibility_live_region	Optional[Literal['none', 'polite', 'assertive']]	How AT announces dynamic changes to this view: "none", "polite", or "assertive" (Android only).	None
test_id	Optional[str]	Stable identifier for UI tests; exposed as resource-id on Android and accessibilityIdentifier on iOS.	None
ref	Optional[Ref]	Optional Ref from use_ref().	None
key	Optional[str]	Stable identity for keyed reconciliation.	None

Returns:

Type	Description
Element	An Element of type "TextInput".

Next steps

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