WebView

An embedded web browser.

Usage

import toga

webview = toga.WebView()

# Request a URL be loaded in the webview.
webview.url = "https://beeware.org"

# Load a URL, and wait (non-blocking) for the page to complete loading
await webview.load_url("https://beeware.org")

# Load static HTML content into the wevbiew.
webview.set_content("https://example.com", "<html>...</html>")

System requirements

  • Using WebView on Windows 10 requires that your users have installed the Edge WebView2 Evergreen Runtime. This is installed by default on Windows 11.

  • Using WebView on Linux requires that the user has installed the system packages for WebKit2, plus the GObject Introspection bindings for WebKit2. The name of the system package required is distribution dependent:

    • Ubuntu 20.04; Debian 11: gir1.2-webkit2-4.0

    • Ubuntu 22.04+; Debian 12+: gir1.2-webkit2-4.1

    • Fedora: webkit2gtk4.1

    • Arch/Manjaro: webkit2gtk-4.1

    • OpenSUSE Tumbleweed: libwebkit2gtk3 typelib(WebKit2)

    • FreeBSD: webkit2-gtk3

    WebView is not fully supported on GTK4. If you want to contribute to the GTK4 WebView implementation, you will require v6.0 of the WebKit2 libraries. This is provided by gir1.2-webkit-6.0 on Ubuntu/Debian, and webkitgtk6.0 on Fedora; for other distributions, consult your distributions’s platform documentation.

Notes

  • Due to app security restrictions, WebView can only display http:// and https:// URLs, not file:// URLs. To serve local file content, run a web server on localhost using a background thread.

  • On macOS 13.3 (Ventura) and later, the content inspector for your app can be opened by running Safari, enabling the developer tools, and selecting your app’s window from the “Develop” menu.

    On macOS versions prior to Ventura, the content inspector is not enabled by default, and is only available when your code is packaged as a full macOS app (e.g., with Briefcase). To enable debugging, run:

    $ defaults write com.example.appname WebKitDeveloperExtras -bool true

    Substituting com.example.appname with the bundle ID for your packaged app.

Reference

class toga.WebView(id=None, style=None, url=None, content=None, user_agent=None, on_webview_load=None, **kwargs)

Bases: Widget

Create a new WebView widget.

Parameters:

  • id (str | None) – The ID for the widget.

  • style (StyleT | None) – A style object. If no style is provided, a default style will be applied to the widget.

  • url (str | None) – The full URL to load in the WebView. If not provided, an empty page will be displayed.

  • content (str | None) – The HTML content to display in the WebView. If content is provided, the value of url will be used as the root URL for the content that is displayed; this URL will be used to resolve any relative URLs in the content. Note: On Android and Windows, if content is specified, any value provided for the url argument will be ignored.

  • user_agent (str | None) – The user agent to use for web requests. If not provided, the default user agent for the platform will be used.

  • on_webview_load (OnWebViewLoadHandler | None) – A handler that will be invoked when the web view finishes loading.

  • kwargs – Initial style properties.

property content

A write-only attribute to set the HTML content currently displayed by the WebView.

web_view.content = "<html>..." is equivalent to calling web_view.set_content("", "<html>...").

Raises:

AttributeError – If an attempt is made to read the page content.

property cookies: CookiesResult

Retrieve cookies from the WebView.

This is an asynchronous property. The value returned by this method must be awaited to obtain the cookies that are currently set.

Note: This property is not currently supported on Android or Linux.

Returns:

An object that returns a CookieJar when awaited.

evaluate_javascript(javascript, on_result=None)

Evaluate a JavaScript expression.

This is an asynchronous method. There is no guarantee that the JavaScript has finished evaluating when this method returns. The object returned by this method can be awaited to obtain the value of the expression.

Note: On Android and Windows, no exception handling is performed. If a JavaScript error occurs, a return value of None will be reported, but no exception will be provided.

Parameters:

  • javascript (str) – The JavaScript expression to evaluate.

  • on_result (OnResultT | None) – DEPRECATED await the return value of this method.

Return type:

JavaScriptResult

async load_url(url)

Load a URL, and wait until the next on_webview_load event.

Note: On Android, this method will return immediately.

Parameters:

url (str) – The URL to load.

Return type:

Future

property on_webview_load: OnWebViewLoadHandler

The handler to invoke when the web view finishes loading.

Rendering web content is a complex, multi-threaded process. Although a page may have completed loading, there’s no guarantee that the page has been fully rendered, or that the widget representation has been fully updated. The number of load events generated by a URL transition or content change can be unpredictable. An on_webview_load event should be interpreted as an indication that some change has occurred, not that a specific change has occurred, or that a specific change has been fully propagated into the rendered content.

Note: This is not currently supported on Android.

set_content(root_url, content)

Set the HTML content of the WebView.

Note: On Android and Windows, the root_url argument is ignored. Calling this method will set the url property to None.

Parameters:

  • root_url (str) – A URL which will be returned by the url property, and used to resolve any relative URLs in the content.

  • content (str) – The HTML content for the WebView

Return type:

None

property url: str | None

The current URL, or None if no URL is currently displayed.

After setting this property, it is not guaranteed that reading the property will immediately return the new value. To be notified once the URL has finished loading, use load_url or on_webview_load.

property user_agent: str

The user agent to use for web requests.

Note: On Windows, this property will return an empty string until the widget has finished initializing.

protocol toga.widgets.webview.OnWebViewLoadHandler

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(widget, **kwargs)

A handler to invoke when the WebView is loaded.

Parameters:

  • widget (WebView) – The WebView that was loaded.

  • kwargs (Any) – Ensures compatibility with arguments added in future versions.

Return type:

object