Struct WebviewBuilder

pub struct WebviewBuilder<R: Runtime> { /* private fields */ }

Available on crate feature unstable only.

A builder for a webview.

Implementations

impl<R: Runtime> WebviewBuilder<R>

pub fn new<L: Into<String>>(label: L, url: WebviewUrl) -> Self

Initializes a webview builder with the given webview label and URL to load.

Known issues

On Windows, this function deadlocks when used in a synchronous command or event handlers, see the Webview2 issue. You should use async commands and separate threads when creating webviews.

Examples

• Create a webview in the setup hook:

tauri::Builder::default()
  .setup(|app| {
    let window = tauri::window::WindowBuilder::new(app, "label").build()?;
    let webview_builder = tauri::webview::WebviewBuilder::new("label", tauri::WebviewUrl::App("index.html".into()));
    let webview = window.add_child(webview_builder, tauri::LogicalPosition::new(0, 0), window.inner_size().unwrap());
    Ok(())
  });

• Create a webview in a separate thread:

tauri::Builder::default()
  .setup(|app| {
    let handle = app.handle().clone();
    std::thread::spawn(move || {
      let window = tauri::window::WindowBuilder::new(&handle, "label").build().unwrap();
      let webview_builder = tauri::webview::WebviewBuilder::new("label", tauri::WebviewUrl::App("index.html".into()));
      window.add_child(webview_builder, tauri::LogicalPosition::new(0, 0), window.inner_size().unwrap());
    });
    Ok(())
  });

• Create a webview in a command:

#[tauri::command]
async fn create_window(app: tauri::AppHandle) {
  let window = tauri::window::WindowBuilder::new(&app, "label").build().unwrap();
  let webview_builder = tauri::webview::WebviewBuilder::new("label", tauri::WebviewUrl::External("https://tauri.app/".parse().unwrap()));
  window.add_child(webview_builder, tauri::LogicalPosition::new(0, 0), window.inner_size().unwrap());
}

pub fn from_config(config: &WindowConfig) -> Self

Initializes a webview builder from a WindowConfig from tauri.conf.json. Keep in mind that you can’t create 2 webviews with the same label so make sure that the initial webview was closed or change the label of the new WebviewBuilder.

Known issues

On Windows, this function deadlocks when used in a synchronous command or event handlers, see the Webview2 issue. You should use async commands and separate threads when creating webviews.

Examples

• Create a webview in a command:

#[tauri::command]
async fn create_window(app: tauri::AppHandle) {
  let window = tauri::window::WindowBuilder::new(&app, "label").build().unwrap();
  let webview_builder = tauri::webview::WebviewBuilder::from_config(&app.config().app.windows.get(0).unwrap().clone());
  window.add_child(webview_builder, tauri::LogicalPosition::new(0, 0), window.inner_size().unwrap());
}

pub fn on_web_resource_request<F: Fn(Request<Vec<u8>>, &mut Response<Cow<'static, [u8]>>) + Send + Sync + 'static>( self, f: F, ) -> Self

Defines a closure to be executed when the webview makes an HTTP request for a web resource, allowing you to modify the response.

Currently only implemented for the tauri URI protocol.

NOTE: Currently this is not executed when using external URLs such as a development server, but it might be implemented in the future. Always check the request URL.

Examples

use tauri::{
  utils::config::{Csp, CspDirectiveSources, WebviewUrl},
  window::WindowBuilder,
  webview::WebviewBuilder,
};
use http::header::HeaderValue;
use std::collections::HashMap;
tauri::Builder::default()
  .setup(|app| {
    let window = tauri::window::WindowBuilder::new(app, "label").build()?;

    let webview_builder = WebviewBuilder::new("core", WebviewUrl::App("index.html".into()))
      .on_web_resource_request(|request, response| {
        if request.uri().scheme_str() == Some("tauri") {
          // if we have a CSP header, Tauri is loading an HTML file
          //  for this example, let's dynamically change the CSP
          if let Some(csp) = response.headers_mut().get_mut("Content-Security-Policy") {
            // use the tauri helper to parse the CSP policy to a map
            let mut csp_map: HashMap<String, CspDirectiveSources> = Csp::Policy(csp.to_str().unwrap().to_string()).into();
            csp_map.entry("script-src".to_string()).or_insert_with(Default::default).push("'unsafe-inline'");
            // use the tauri helper to get a CSP string from the map
            let csp_string = Csp::from(csp_map).to_string();
            *csp = HeaderValue::from_str(&csp_string).unwrap();
          }
        }
      });

    let webview = window.add_child(webview_builder, tauri::LogicalPosition::new(0, 0), window.inner_size().unwrap())?;

    Ok(())
  });

pub fn on_navigation<F: Fn(&Url) -> bool + Send + 'static>(self, f: F) -> Self

Defines a closure to be executed when the webview navigates to a URL. Returning false cancels the navigation.

Examples

use tauri::{
  utils::config::{Csp, CspDirectiveSources, WebviewUrl},
  window::WindowBuilder,
  webview::WebviewBuilder,
};
use http::header::HeaderValue;
use std::collections::HashMap;
tauri::Builder::default()
  .setup(|app| {
    let window = tauri::window::WindowBuilder::new(app, "label").build()?;

    let webview_builder = WebviewBuilder::new("core", WebviewUrl::App("index.html".into()))
      .on_navigation(|url| {
        // allow the production URL or localhost on dev
        url.scheme() == "tauri" || (cfg!(dev) && url.host_str() == Some("localhost"))
      });

    let webview = window.add_child(webview_builder, tauri::LogicalPosition::new(0, 0), window.inner_size().unwrap())?;
    Ok(())
  });

pub fn on_download<F: Fn(Webview<R>, DownloadEvent<'_>) -> bool + Send + Sync + 'static>( self, f: F, ) -> Self

Set a download event handler to be notified when a download is requested or finished.

Returning false prevents the download from happening on a DownloadEvent::Requested event.

Examples

use tauri::{
  utils::config::{Csp, CspDirectiveSources, WebviewUrl},
  window::WindowBuilder,
  webview::{DownloadEvent, WebviewBuilder},
};

tauri::Builder::default()
  .setup(|app| {
    let window = WindowBuilder::new(app, "label").build()?;
    let webview_builder = WebviewBuilder::new("core", WebviewUrl::App("index.html".into()))
      .on_download(|webview, event| {
        match event {
          DownloadEvent::Requested { url, destination } => {
            println!("downloading {}", url);
            *destination = "/home/tauri/target/path".into();
          }
          DownloadEvent::Finished { url, path, success } => {
            println!("downloaded {} to {:?}, success: {}", url, path, success);
          }
          _ => (),
        }
        // let the download start
        true
      });

    let webview = window.add_child(webview_builder, tauri::LogicalPosition::new(0, 0), window.inner_size().unwrap())?;
    Ok(())
  });

pub fn on_page_load<F: Fn(Webview<R>, PageLoadPayload<'_>) + Send + Sync + 'static>( self, f: F, ) -> Self

Defines a closure to be executed when a page load event is triggered. The event can be either PageLoadEvent::Started if the page has started loading or PageLoadEvent::Finished when the page finishes loading.

Examples

use tauri::{
  utils::config::{Csp, CspDirectiveSources, WebviewUrl},
  window::WindowBuilder,
  webview::{PageLoadEvent, WebviewBuilder},
};
use http::header::HeaderValue;
use std::collections::HashMap;
tauri::Builder::default()
  .setup(|app| {
    let window = tauri::window::WindowBuilder::new(app, "label").build()?;
    let webview_builder = WebviewBuilder::new("core", WebviewUrl::App("index.html".into()))
      .on_page_load(|webview, payload| {
        match payload.event() {
          PageLoadEvent::Started => {
            println!("{} finished loading", payload.url());
          }
          PageLoadEvent::Finished => {
            println!("{} finished loading", payload.url());
          }
        }
      });
    let webview = window.add_child(webview_builder, tauri::LogicalPosition::new(0, 0), window.inner_size().unwrap())?;
    Ok(())
  });

impl<R: Runtime> WebviewBuilder<R>

Webview attributes.

pub fn accept_first_mouse(self, accept: bool) -> Self

Sets whether clicking an inactive window also clicks through to the webview.

pub fn initialization_script(self, script: impl Into<String>) -> Self

Adds the provided JavaScript to a list of scripts that should be run after the global object has been created, but before the HTML document has been parsed and before any other script included by the HTML document is run.

Since it runs on all top-level document navigations, it’s recommended to check the window.location to guard your script from running on unexpected origins.

This is executed only on the main frame. If you only want to run it in all frames, use Self::initialization_script_for_all_frames instead.

Platform-specific

• Windows: scripts are always added to subframes.
• Android: When addDocumentStartJavaScript is not supported, we prepend initialization scripts to each HTML head (implementation only supported on custom protocol URLs). For remote URLs, we use onPageStarted which is not guaranteed to run before other scripts.

Examples

use tauri::{WindowBuilder, Runtime};

const INIT_SCRIPT: &str = r#"
  if (window.location.origin === 'https://tauri.app') {
    console.log("hello world from js init script");

    window.__MY_CUSTOM_PROPERTY__ = { foo: 'bar' };
  }
"#;

fn main() {
  tauri::Builder::default()
    .setup(|app| {
      let window = tauri::window::WindowBuilder::new(app, "label").build()?;
      let webview_builder = tauri::webview::WebviewBuilder::new("label", tauri::WebviewUrl::App("index.html".into()))
        .initialization_script(INIT_SCRIPT);
      let webview = window.add_child(webview_builder, tauri::LogicalPosition::new(0, 0), window.inner_size().unwrap())?;
      Ok(())
    });
}

pub fn initialization_script_for_all_frames( self, script: impl Into<String>, ) -> Self

Adds the provided JavaScript to a list of scripts that should be run after the global object has been created, but before the HTML document has been parsed and before any other script included by the HTML document is run.

Since it runs on all top-level document navigations and also child frame page navigations, it’s recommended to check the window.location to guard your script from running on unexpected origins.

This is executed on all frames (main frame and also sub frames). If you only want to run the script in the main frame, use Self::initialization_script instead.

Platform-specific

• Android: When addDocumentStartJavaScript is not supported, we prepend initialization scripts to each HTML head (implementation only supported on custom protocol URLs). For remote URLs, we use onPageStarted which is not guaranteed to run before other scripts.

Examples

use tauri::{WindowBuilder, Runtime};

const INIT_SCRIPT: &str = r#"
  if (window.location.origin === 'https://tauri.app') {
    console.log("hello world from js init script");

    window.__MY_CUSTOM_PROPERTY__ = { foo: 'bar' };
  }
"#;

fn main() {
  tauri::Builder::default()
    .setup(|app| {
      let window = tauri::window::WindowBuilder::new(app, "label").build()?;
      let webview_builder = tauri::webview::WebviewBuilder::new("label", tauri::WebviewUrl::App("index.html".into()))
        .initialization_script_for_all_frames(INIT_SCRIPT);
      let webview = window.add_child(webview_builder, tauri::LogicalPosition::new(0, 0), window.inner_size().unwrap())?;
      Ok(())
    });
}

pub fn user_agent(self, user_agent: &str) -> Self

Set the user agent for the webview

pub fn additional_browser_args(self, additional_args: &str) -> Self

Set additional arguments for the webview.

Platform-specific

• macOS / Linux / Android / iOS: Unsupported.

Warning

By default wry passes --disable-features=msWebOOUI,msPdfOOUI,msSmartScreenProtection so if you use this method, you also need to disable these components by yourself if you want.

pub fn data_directory(self, data_directory: PathBuf) -> Self

Data directory for the webview.

pub fn disable_drag_drop_handler(self) -> Self

Disables the drag and drop handler. This is required to use HTML5 drag and drop APIs on the frontend on Windows.

pub fn enable_clipboard_access(self) -> Self

Enables clipboard access for the page rendered on Linux and Windows.

macOS doesn’t provide such method and is always enabled by default, but you still need to add menu item accelerators to use shortcuts.

pub fn incognito(self, incognito: bool) -> Self

Enable or disable incognito mode for the WebView.

Platform-specific:

• Windows: Requires WebView2 Runtime version 101.0.1210.39 or higher, does nothing on older versions, see https://learn.microsoft.com/en-us/microsoft-edge/webview2/release-notes/archive?tabs=dotnetcsharp#10121039
• Android: Unsupported.
• macOS / iOS: Uses the nonPersistent DataStore

pub fn proxy_url(self, url: Url) -> Self

Set a proxy URL for the WebView for all network requests.

Must be either a http:// or a socks5:// URL.

Platform-specific

• macOS: Requires the macos-proxy feature flag and only compiles for macOS 14+.

pub fn transparent(self, transparent: bool) -> Self

Available on non-macOS or crate feature macos-private-api only.

Enable or disable transparency for the WebView.

pub fn focused(self, focus: bool) -> Self

Whether the webview should be focused or not.

pub fn auto_resize(self) -> Self

Sets the webview to automatically grow and shrink its size and position when the parent window resizes.

pub fn zoom_hotkeys_enabled(self, enabled: bool) -> Self

Whether page zooming by hotkeys and mousewheel should be enabled or not.

Platform-specific:

• Windows: Controls WebView2’s IsZoomControlEnabled setting.

• MacOS / Linux: Injects a polyfill that zooms in and out with Ctrl/Cmd + [- = +] hotkeys or mousewheel events, 20% in each step, ranging from 20% to 1000%. Requires core:webview:allow-set-webview-zoom permission

• Android / iOS: Unsupported.

pub fn browser_extensions_enabled(self, enabled: bool) -> Self

Whether browser extensions can be installed for the webview process

Platform-specific:

• Windows: Enables the WebView2 environment’s AreBrowserExtensionsEnabled
• MacOS / Linux / iOS / Android - Unsupported.

pub fn extensions_path(self, path: impl AsRef<Path>) -> Self

Set the path from which to load extensions from. Extensions stored in this path should be unpacked Chrome extensions on Windows, and compiled .so extensions on Linux.

Platform-specific:

• Windows: Browser extensions must first be enabled. See browser_extensions_enabled
• MacOS / iOS / Android - Unsupported.

pub fn data_store_identifier(self, data_store_identifier: [u8; 16]) -> Self

Initialize the WebView with a custom data store identifier. Can be used as a replacement for data_directory not being available in WKWebView.

• macOS / iOS: Available on macOS >= 14 and iOS >= 17
• Windows / Linux / Android: Unsupported.

Note: Enable incognito mode to use the nonPersistent DataStore.

pub fn use_https_scheme(self, enabled: bool) -> Self

Sets whether the custom protocols should use https://<scheme>.localhost instead of the default http://<scheme>.localhost on Windows and Android. Defaults to false.

Note

Using a https scheme will NOT allow mixed content when trying to fetch http endpoints and therefore will not match the behavior of the <scheme>://localhost protocols used on macOS and Linux.

Warning

Changing this value between releases will change the IndexedDB, cookies and localstorage location and your app will not be able to access the old data.

pub fn devtools(self, enabled: bool) -> Self

Whether web inspector, which is usually called browser devtools, is enabled or not. Enabled by default.

This API works in debug builds, but requires devtools feature flag to enable it in release builds.

Platform-specific

• macOS: This will call private functions on macOS
• Android: Open chrome://inspect/#devices in Chrome to get the devtools window. Wry’s WebView devtools API isn’t supported on Android.
• iOS: Open Safari > Develop > [Your Device Name] > [Your WebView] to get the devtools window.

pub fn background_color(self, color: Color) -> Self

Set the webview background color.

Platform-specific:

• macOS / iOS: Not implemented.
• Windows: On Windows 7, alpha channel is ignored.
• Windows: On Windows 8 and newer, if alpha channel is not 0, it will be ignored.

pub fn background_throttling(self, policy: BackgroundThrottlingPolicy) -> Self

Change the default background throttling behaviour.

By default, browsers use a suspend policy that will throttle timers and even unload the whole tab (view) to free resources after roughly 5 minutes when a view became minimized or hidden. This will pause all tasks until the documents visibility state changes back from hidden to visible by bringing the view back to the foreground.

Platform-specific

• Linux / Windows / Android: Unsupported. Workarounds like a pending WebLock transaction might suffice.
• iOS: Supported since version 17.0+.
• macOS: Supported since version 14.0+.

see https://github.com/tauri-apps/tauri/issues/5250#issuecomment-2569380578

pub fn disable_javascript(self) -> Self

Whether JavaScript should be disabled.