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() -> pn.Node:
    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; they queue behind the pending mount, so they reach the view the last commit created. Methods that need an answer from the native view are async and await it without blocking the application loop. 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	Queue a native view command by name; returns a future for its result.
measure_in_window	The view's frame relative to its screen, read from the renderer core.

command

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

Queue a native view command by name; returns a future for 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. Await the future for a command that answers.

measure_in_window async

measure_in_window() -> Optional[LayoutEvent]

The view's frame relative to its screen, read from the renderer core.

Unlike frame, which is relative to the parent and updated after each layout, this answers for the latest layout immediately, and works for views the core flattened out of the mounted tree.

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.