feat: Expose ScrollBarStyle webview option to tauri. (#14089)

* Expose `ScrollBarStyle` webview option to tauri.

This commit exposes the scroll_bar_style option from wry via the tauri
WebviewWindowBuilder API. By itself, the commit does not include changes
to the configuration file or JavaScript APIs: These will be added in a
later commit.

* Fix a compile error on macOS and Linux.

* Add `scroll_bar_style` to WindowConfig.

This commit exposes the `scroll_bar_style` option in tauri.conf.json/
.json5/.toml as `scrollBarStyle` and `scroll-bar-style`.

* Expose `scroll_bar_style` to JavaScript API.

This commit exposes the `scroll_bar_style` in the options object passed
to the JavaScript API `Webview` and `WebviewWindow` constructors.

While testing this, I discovered that on Windows, attempting to create
a webview from the JavaScript API will cause the hosting window to
immediately hang if it attempts to use the same data directory as
another webview without sharing the same environment options. This
commit includes no mitigation for this behaviour, as I will be opening
a separate issue about it at some point in the near future.

* Document WebView2 environment requirements.

This commit adds a message to the documentation for all components of
the `scroll_bar_style` configuration option, telling users that all
webviews that use the same data directory must use the same value for
this option.

* Fix formatting.

* Add change files to .changes directory.

* Remove `tauri-schema-generator` from change file.

* Remove quotes from change tags.

* Add tags to change files.

I did not realise that these were needed, as the pull request that I
used as my reference when building this feature did not have them.

* update conf

---------

Co-authored-by: Lucas Nogueira <lucas@tauri.app>

Author: Themayu

.changes/14089-expose-scrollbarstyle-webview-option-to-tauri-api.md

@@ -0,0 +1,5 @@
+---
+"@tauri-apps/api": minor:feat
+---
+
+Adds the `scrollBarStyle` option to the Webview and WebviewBuilder constructors.

.changes/14089-expose-scrollbarstyle-webview-option-to-tauri-config.md

@@ -0,0 +1,6 @@
+---
+"tauri-cli": minor:feat
+"tauri-utils": minor:feat
+---
+
+Adds the `scrollBarStyle` option to the window configuration.

.changes/14089-expose-scrollbarstyle-webview-option-to-tauri.md

@@ -0,0 +1,9 @@
+---
+"tauri-runtime-wry": minor:feat
+"tauri-runtime": minor:feat
+"tauri": minor:feat
+---
+
+Adds the `scroll_bar_style` option to the Webview and WebviewWindow builders.
+The possible values for this option are gated behind conditional compilation
+flags, and will need to be applied using conditional compilation if customised.

crates/tauri-cli/config.schema.json

@@ -593,6 +593,15 @@
           },
           "maxItems": 16,
           "minItems": 16
+        },
+        "scrollBarStyle": {
+          "description": "Specifies the native scrollbar style to use with the webview.\n CSS styles that modify the scrollbar are applied on top of the native appearance configured here.\n\n Defaults to `default`, which is the browser default.\n\n ## Platform-specific\n\n - **Windows**:\n   - `fluentOverlay` requires WebView2 Runtime version 125.0.2535.41 or higher,\n     and does nothing on older versions.\n   - This option must be given the same value for all webviews that target the same data directory.\n - **Linux / Android / iOS / macOS**: Unsupported. Only supports `Default` and performs no operation.",
+          "default": "default",
+          "allOf": [
+            {
+              "$ref": "#/definitions/ScrollBarStyle"
+            }
+          ]
         }
       },
       "additionalProperties": false
@@ -1112,6 +1121,25 @@
         }
       ]
     },
+    "ScrollBarStyle": {
+      "description": "The scrollbar style to use in the webview.\n\n ## Platform-specific\n\n - **Windows**: This option must be given the same value for all webviews that target the same data directory.",
+      "oneOf": [
+        {
+          "description": "The scrollbar style to use in the webview.",
+          "type": "string",
+          "enum": [
+            "default"
+          ]
+        },
+        {
+          "description": "Fluent UI style overlay scrollbars. **Windows Only**\n\n Requires WebView2 Runtime version 125.0.2535.41 or higher, does nothing on older versions,\n see https://learn.microsoft.com/en-us/microsoft-edge/webview2/release-notes/?tabs=dotnetcsharp#10253541",
+          "type": "string",
+          "enum": [
+            "fluentOverlay"
+          ]
+        }
+      ]
+    },
     "SecurityConfig": {
       "description": "Security configuration.\n\n See more: <https://v2.tauri.app/reference/config/#securityconfig>",
       "type": "object",

crates/tauri-runtime-wry/src/lib.rs

@@ -18,6 +18,8 @@ use http::Request;
 use objc2::ClassType;
 use raw_window_handle::{DisplayHandle, HasDisplayHandle, HasWindowHandle};
 
+#[cfg(windows)]
+use tauri_runtime::webview::ScrollBarStyle;
 use tauri_runtime::{
   dpi::{LogicalPosition, LogicalSize, PhysicalPosition, PhysicalSize, Position, Size},
   monitor::Monitor,
@@ -79,6 +81,8 @@ use tauri_utils::{
   Theme,
 };
 use url::Url;
+#[cfg(windows)]
+use wry::ScrollBarStyle as WryScrollBarStyle;
 use wry::{
   DragDropEvent as WryDragDropEvent, ProxyConfig, ProxyEndpoint, WebContext as WryWebContext,
   WebView, WebViewBuilder,
@@ -4833,6 +4837,13 @@ You may have it installed on another user account, but it is not available for t
       TaoTheme::Light => wry::Theme::Light,
       _ => wry::Theme::Light,
     });
+
+    webview_builder =
+      webview_builder.with_scroll_bar_style(match webview_attributes.scroll_bar_style {
+        ScrollBarStyle::Default => WryScrollBarStyle::Default,
+        ScrollBarStyle::FluentOverlay => WryScrollBarStyle::FluentOverlay,
+        _ => unreachable!(),
+      });
   }
 
   #[cfg(windows)]

crates/tauri-runtime/src/webview.rs

@@ -10,7 +10,8 @@ use crate::{window::is_label_valid, Rect, Runtime, UserEvent};
 
 use http::Request;
 use tauri_utils::config::{
-  BackgroundThrottlingPolicy, Color, WebviewUrl, WindowConfig, WindowEffectsConfig,
+  BackgroundThrottlingPolicy, Color, ScrollBarStyle as ConfigScrollBarStyle, WebviewUrl,
+  WindowConfig, WindowEffectsConfig,
 };
 use url::Url;
 
@@ -170,6 +171,26 @@ pub enum NewWindowResponse {
   Deny,
 }
 
+/// The scrollbar style to use in the webview.
+///
+/// ## Platform-specific
+///
+/// - **Windows**: This option must be given the same value for all webviews that target the same data directory.
+#[non_exhaustive]
+#[derive(Debug, Clone, Copy, Default)]
+pub enum ScrollBarStyle {
+  #[default]
+  /// The default scrollbar style for the webview.
+  Default,
+
+  #[cfg(windows)]
+  /// Fluent UI style overlay scrollbars. **Windows Only**
+  ///
+  /// Requires WebView2 Runtime version 125.0.2535.41 or higher, does nothing on older versions,
+  /// see https://learn.microsoft.com/en-us/microsoft-edge/webview2/release-notes/?tabs=dotnetcsharp#10253541
+  FluentOverlay,
+}
+
 /// A webview that has yet to be built.
 pub struct PendingWebview<T: UserEvent, R: Runtime<T>> {
   /// The label that the webview will be named.
@@ -340,6 +361,7 @@ pub struct WebviewAttributes {
   /// on macOS and iOS there is a link preview on long pressing links, this is enabled by default.
   /// see https://docs.rs/objc2-web-kit/latest/objc2_web_kit/struct.WKWebView.html#method.allowsLinkPreview
   pub allow_link_preview: bool,
+  pub scroll_bar_style: ScrollBarStyle,
   /// Allows overriding the the keyboard accessory view on iOS.
   /// Returning `None` effectively removes the view.
   ///
@@ -404,7 +426,13 @@ impl From<&WindowConfig> for WebviewAttributes {
       .use_https_scheme(config.use_https_scheme)
       .browser_extensions_enabled(config.browser_extensions_enabled)
       .background_throttling(config.background_throttling.clone())
-      .devtools(config.devtools);
+      .devtools(config.devtools)
+      .scroll_bar_style(match config.scroll_bar_style {
+        ConfigScrollBarStyle::Default => ScrollBarStyle::Default,
+        #[cfg(windows)]
+        ConfigScrollBarStyle::FluentOverlay => ScrollBarStyle::FluentOverlay,
+        _ => ScrollBarStyle::Default,
+      });
 
     #[cfg(any(not(target_os = "macos"), feature = "macos-private-api"))]
     {
@@ -478,6 +506,7 @@ impl WebviewAttributes {
       background_throttling: None,
       javascript_disabled: false,
       allow_link_preview: true,
+      scroll_bar_style: ScrollBarStyle::Default,
       #[cfg(target_os = "ios")]
       input_accessory_view_builder: None,
       #[cfg(windows)]
@@ -750,6 +779,25 @@ impl WebviewAttributes {
     self.background_throttling = policy;
     self
   }
+
+  /// Specifies the native scrollbar style to use with the webview.
+  /// CSS styles that modify the scrollbar are applied on top of the native appearance configured here.
+  ///
+  /// Defaults to [`ScrollBarStyle::Default`], which is the browser default.
+  ///
+  /// ## Platform-specific
+  ///
+  /// - **Windows**:
+  ///   - [`ScrollBarStyle::FluentOverlay`] requires WebView2 Runtime version 125.0.2535.41 or higher,
+  ///     and does nothing on older versions.
+  ///   - This option must be given the same value for all webviews that target the same data directory. Use
+  ///     [`WebviewAttributes::data_directory`] to change data directories if needed.
+  /// - **Linux / Android / iOS / macOS**: Unsupported. Only supports `Default` and performs no operation.
+  #[must_use]
+  pub fn scroll_bar_style(mut self, style: ScrollBarStyle) -> Self {
+    self.scroll_bar_style = style;
+    self
+  }
 }
 
 /// IPC handler.

crates/tauri-schema-generator/schemas/config.schema.json

@@ -593,6 +593,15 @@
           },
           "maxItems": 16,
           "minItems": 16
+        },
+        "scrollBarStyle": {
+          "description": "Specifies the native scrollbar style to use with the webview.\n CSS styles that modify the scrollbar are applied on top of the native appearance configured here.\n\n Defaults to `default`, which is the browser default.\n\n ## Platform-specific\n\n - **Windows**:\n   - `fluentOverlay` requires WebView2 Runtime version 125.0.2535.41 or higher,\n     and does nothing on older versions.\n   - This option must be given the same value for all webviews that target the same data directory.\n - **Linux / Android / iOS / macOS**: Unsupported. Only supports `Default` and performs no operation.",
+          "default": "default",
+          "allOf": [
+            {
+              "$ref": "#/definitions/ScrollBarStyle"
+            }
+          ]
         }
       },
       "additionalProperties": false
@@ -1112,6 +1121,25 @@
         }
       ]
     },
+    "ScrollBarStyle": {
+      "description": "The scrollbar style to use in the webview.\n\n ## Platform-specific\n\n - **Windows**: This option must be given the same value for all webviews that target the same data directory.",
+      "oneOf": [
+        {
+          "description": "The scrollbar style to use in the webview.",
+          "type": "string",
+          "enum": [
+            "default"
+          ]
+        },
+        {
+          "description": "Fluent UI style overlay scrollbars. **Windows Only**\n\n Requires WebView2 Runtime version 125.0.2535.41 or higher, does nothing on older versions,\n see https://learn.microsoft.com/en-us/microsoft-edge/webview2/release-notes/?tabs=dotnetcsharp#10253541",
+          "type": "string",
+          "enum": [
+            "fluentOverlay"
+          ]
+        }
+      ]
+    },
     "SecurityConfig": {
       "description": "Security configuration.\n\n See more: <https://v2.tauri.app/reference/config/#securityconfig>",
       "type": "object",

crates/tauri-utils/src/config.rs

@@ -1586,6 +1586,27 @@ pub enum PreventOverflowConfig {
   Margin(PreventOverflowMargin),
 }
 
+/// The scrollbar style to use in the webview.
+///
+/// ## Platform-specific
+///
+/// - **Windows**: This option must be given the same value for all webviews that target the same data directory.
+#[derive(Debug, PartialEq, Clone, Serialize, Deserialize, Default)]
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[non_exhaustive]
+pub enum ScrollBarStyle {
+  #[default]
+  /// The scrollbar style to use in the webview.
+  Default,
+
+  /// Fluent UI style overlay scrollbars. **Windows Only**
+  ///
+  /// Requires WebView2 Runtime version 125.0.2535.41 or higher, does nothing on older versions,
+  /// see https://learn.microsoft.com/en-us/microsoft-edge/webview2/release-notes/?tabs=dotnetcsharp#10253541
+  FluentOverlay,
+}
+
 /// The window configuration object.
 ///
 /// See more: <https://v2.tauri.app/reference/config/#windowconfig>
@@ -1919,6 +1940,21 @@ pub struct WindowConfig {
   /// - **Windows / Linux / Android**: Unsupported.
   #[serde(default, alias = "data-store-identifier")]
   pub data_store_identifier: Option<[u8; 16]>,
+
+  /// Specifies the native scrollbar style to use with the webview.
+  /// CSS styles that modify the scrollbar are applied on top of the native appearance configured here.
+  ///
+  /// Defaults to `default`, which is the browser default.
+  ///
+  /// ## Platform-specific
+  ///
+  /// - **Windows**:
+  ///   - `fluentOverlay` requires WebView2 Runtime version 125.0.2535.41 or higher,
+  ///     and does nothing on older versions.
+  ///   - This option must be given the same value for all webviews that target the same data directory.
+  /// - **Linux / Android / iOS / macOS**: Unsupported. Only supports `Default` and performs no operation.
+  #[serde(default, alias = "scroll-bar-style")]
+  pub scroll_bar_style: ScrollBarStyle,
 }
 
 impl Default for WindowConfig {
@@ -1980,6 +2016,7 @@ impl Default for WindowConfig {
       disable_input_accessory_view: false,
       data_directory: None,
       data_store_identifier: None,
+      scroll_bar_style: ScrollBarStyle::Default,
     }
   }
 }
@@ -3430,6 +3467,17 @@ mod build {
     }
   }
 
+  impl ToTokens for ScrollBarStyle {
+    fn to_tokens(&self, tokens: &mut TokenStream) {
+      let prefix = quote! { ::tauri::utils::config::ScrollBarStyle };
+
+      tokens.append_all(match self {
+        Self::Default => quote! { #prefix::Default },
+        Self::FluentOverlay => quote! { #prefix::FluentOverlay },
+      })
+    }
+  }
+
   impl ToTokens for WindowConfig {
     fn to_tokens(&self, tokens: &mut TokenStream) {
       let label = str_lit(&self.label);
@@ -3488,6 +3536,7 @@ mod build {
       let disable_input_accessory_view = self.disable_input_accessory_view;
       let data_directory = opt_lit(self.data_directory.as_ref().map(path_buf_lit).as_ref());
       let data_store_identifier = opt_vec_lit(self.data_store_identifier, identity);
+      let scroll_bar_style = &self.scroll_bar_style;
 
       literal_struct!(
         tokens,
@@ -3547,7 +3596,8 @@ mod build {
         allow_link_preview,
         disable_input_accessory_view,
         data_directory,
-        data_store_identifier
+        data_store_identifier,
+        scroll_bar_style
       );
     }
   }

crates/tauri/scripts/bundle.global.js

@@ -18,7 +18,7 @@ pub use cookie;
 use http::HeaderMap;
 use serde::Serialize;
 use tauri_macros::default_runtime;
-pub use tauri_runtime::webview::{NewWindowFeatures, PageLoadEvent};
+pub use tauri_runtime::webview::{NewWindowFeatures, PageLoadEvent, ScrollBarStyle};
 // Remove this re-export in v3
 pub use tauri_runtime::Cookie;
 #[cfg(desktop)]
@@ -1165,6 +1165,25 @@ fn main() {
     self
   }
 
+  /// Specifies the native scrollbar style to use with the webview.
+  /// CSS styles that modify the scrollbar are applied on top of the native appearance configured here.
+  ///
+  /// Defaults to [`ScrollBarStyle::Default`], which is the browser default.
+  ///
+  /// ## Platform-specific
+  ///
+  /// - **Windows**:
+  ///   - [`ScrollBarStyle::FluentOverlay`] requires WebView2 Runtime version 125.0.2535.41 or higher,
+  ///     and does nothing on older versions.
+  ///   - This option must be given the same value for all webviews that target the same data directory. Use
+  ///     [`WebviewBuilder::data_directory`] to change data directories if needed.
+  /// - **Linux / Android / iOS / macOS**: Unsupported. Only supports `Default` and performs no operation.
+  #[must_use]
+  pub fn scroll_bar_style(mut self, style: ScrollBarStyle) -> Self {
+    self.webview_attributes = self.webview_attributes.scroll_bar_style(style);
+    self
+  }
+
   /// Whether to show a link preview when long pressing on links. Available on macOS and iOS only.
   ///
   /// Default is true.