Handles

Typed imperative handles published on ref.current when a Ref from use_ref is passed to a built-in element. The reconciler picks the handle class by element type after commit and clears ref.current back to None on unmount. Methods that act on the view are plain calls; methods that need an answer from the native view are async. Composite components (FlatList, SectionList) publish a ListController instead, through use_imperative_handle.

import pythonnative as pn


@pn.component
def Search():
    field = pn.use_ref()

    def focus_field():
        if field.current is not None:
            field.current.focus()

    pn.use_effect(focus_field, [])
    return pn.TextInput(placeholder="Search", ref=field)

Typed imperative handles published on ref.current for built-in elements.

When a Ref is passed to a built-in element, the reconciler publishes a handle chosen by element type on ref.current after commit and clears it back to None on unmount:

Element	ref.current
TextInput	TextInputHandle
ScrollView	ScrollViewHandle
WebView	WebViewHandle
everything else	ViewHandle

Every handle exposes the view's tag, its type_name, and frame (the last committed LayoutEvent, written by the layout pass). Methods that act on the view are plain calls; methods that need an answer from the native view are async. Composite components (FlatList, SectionList) publish their own ListController instead.

Example

import pythonnative as pn

@pn.component
def Search():
    field = pn.use_ref()
    pn.use_effect(lambda: field.current and field.current.focus(), [])
    return pn.TextInput(placeholder="Search", ref=field)

Classes:

Name	Description
ScrollOffset	A scroll container's content offset in logical units.
ViewHandle	The imperative handle for a mounted built-in element.
TextInputHandle	Handle for TextInput.
ScrollViewHandle	Handle for ScrollView.
WebViewHandle	Handle for WebView.

Functions:

Name	Description
make_handle	Build the handle the reconciler publishes on ref.current for type_name.

Attributes:

Name	Type	Description
HANDLE_TYPES	Dict[str, type[ViewHandle]]	Element types with a specialized handle; every other type gets a ViewHandle.

HANDLE_TYPES module-attribute

HANDLE_TYPES: Dict[str, type[ViewHandle]] = {
    "TextInput": TextInputHandle,
    "ScrollView": ScrollViewHandle,
    "WebView": WebViewHandle,
}

Element types with a specialized handle; every other type gets a ViewHandle.

ScrollOffset dataclass

ScrollOffset(x: float, y: float)

A scroll container's content offset in logical units.

ViewHandle

ViewHandle(tag: int, type_name: str, backend: Any)

The imperative handle for a mounted built-in element.

Attributes:

Name	Type	Description
tag		The reconciler-assigned view tag.
type_name		The element type ("View", "Text", ...).
frame	Optional[LayoutEvent]	The last committed frame as a LayoutEvent, or None before the first layout. Written by the layout pass.

Methods:

Name	Description
command	Run a native view command by name and return its result.

command

command(name: str, **args: Any) -> Any

Run a native view command by name and return its result.

The typed methods on the subclasses are thin wrappers over this; it stays public for commands a custom native component declares in its own contract.

TextInputHandle

TextInputHandle(tag: int, type_name: str, backend: Any)

Bases: ViewHandle

Handle for TextInput.

Methods:

Name	Description
focus	Give the field keyboard focus.
blur	Remove keyboard focus from the field.
clear	Empty the field (on_change reports the empty string).
select_all	Select the whole text.
set_selection	Move the caret to start, or select start to end (UTF-16 offsets).
get_value	Return the field's current text as the native view holds it.

focus

focus() -> None

Give the field keyboard focus.

blur

blur() -> None

Remove keyboard focus from the field.

clear

clear() -> None

Empty the field (on_change reports the empty string).

select_all

select_all() -> None

Select the whole text.

set_selection

set_selection(
    start: int, end: Optional[int] = None
) -> None

Move the caret to start, or select start to end (UTF-16 offsets).

get_value async

get_value() -> str

Return the field's current text as the native view holds it.

ScrollViewHandle

ScrollViewHandle(tag: int, type_name: str, backend: Any)

Bases: ViewHandle

Handle for ScrollView.

Methods:

Name	Description
scroll_to	Scroll to a content offset; an omitted axis keeps its current offset.
scroll_to_end	Scroll to the end of the content along the scroll axis.
flash_scroll_indicators	Briefly show the scroll indicators.
get_scroll_offset	Return the current content offset.

scroll_to

scroll_to(
    x: Optional[float] = None,
    y: Optional[float] = None,
    animated: bool = True,
) -> None

Scroll to a content offset; an omitted axis keeps its current offset.

scroll_to_end

scroll_to_end(animated: bool = True) -> None

Scroll to the end of the content along the scroll axis.

flash_scroll_indicators

flash_scroll_indicators() -> None

Briefly show the scroll indicators.

get_scroll_offset async

get_scroll_offset() -> ScrollOffset

Return the current content offset.

WebViewHandle

WebViewHandle(tag: int, type_name: str, backend: Any)

Bases: ViewHandle

Handle for WebView.

Methods:

Name	Description
reload	Reload the current page.
go_back	Navigate back in the page history.
go_forward	Navigate forward in the page history.
stop_loading	Stop the current load.
load_url	Navigate to url.
inject_javascript	Evaluate script in the page without waiting for a result.
eval_js	Evaluate script in the page and return its result as a string.
can_go_back	Whether the page history has an entry to go back to.
can_go_forward	Whether the page history has an entry to go forward to.
get_url	Return the URL of the current page.

reload

reload() -> None

Reload the current page.

go_back

go_back() -> None

Navigate back in the page history.

go_forward

go_forward() -> None

Navigate forward in the page history.

stop_loading

stop_loading() -> None

Stop the current load.

load_url

load_url(url: str) -> None

Navigate to url.

inject_javascript

inject_javascript(script: str) -> None

Evaluate script in the page without waiting for a result.

eval_js async

eval_js(script: str) -> str

Evaluate script in the page and return its result as a string.

The page answers asynchronously, so this awaits the WebViews native module rather than issuing a view command. Strings come back as-is, null and undefined as "", and other values in their JSON form ("42", "true").

Raises:

Type	Description
NativeModuleError	If the script throws or the page can't be reached (a cross-origin page in the browser preview).

can_go_back async

can_go_back() -> bool

Whether the page history has an entry to go back to.

can_go_forward async

can_go_forward() -> bool

Whether the page history has an entry to go forward to.

get_url async

get_url() -> str

Return the URL of the current page.

make_handle

make_handle(
    type_name: str, tag: int, backend: Any
) -> ViewHandle

Build the handle the reconciler publishes on ref.current for type_name.

Next steps

• Read the usage patterns in Refs and handles.
• Scroll a list imperatively with ListController; see the Lists guide.
• Call a custom component's own commands through ViewHandle.command; see Custom native components.