Skip to content

feat(webview2): add with_native_window_occlusion option#1742

Open
podheitor wants to merge 1 commit into
tauri-apps:devfrom
podheitor:feat-native-window-occlusion
Open

feat(webview2): add with_native_window_occlusion option#1742
podheitor wants to merge 1 commit into
tauri-apps:devfrom
podheitor:feat-native-window-occlusion

Conversation

@podheitor
Copy link
Copy Markdown

feat(webview2): add with_native_window_occlusion option

What

Adds a Windows-specific builder option WebViewBuilderExtWindows::with_native_window_occlusion(bool) that lets an app opt out of WebView2's native window occlusion detection.

When set to false, wry appends CalculateNativeWinOcclusion to the --disable-features list it already passes by default. It defaults to true, so current behavior is unchanged unless you explicitly opt out.

Why

On Windows, WebView2 stops (or never starts) rendering a webview whose host window is hidden or fully occluded, to save resources. That's fine for a single foreground webview, but it breaks apps that pre-create several webviews and show/hide them on demand (tabbed browsers, multi-service messaging shells, etc.): a webview created while hidden may never bring up its render surface and paints blank the first time it's shown.

This is a long-standing pain point with no in-library workaround today:

Disabling CalculateNativeWinOcclusion is the documented lever for this, but the only way to reach it today is with_additional_browser_args, which fully overrides wry's default args (the mini-menu / SmartScreen / autoplay / proxy flags) — so you lose all of those unless you reproduce them by hand. This option exposes just the occlusion toggle while keeping wry's defaults intact.

How

  • New field native_window_occlusion: bool on the Windows PlatformSpecificWebViewAttributes (defaults to true).
  • New trait method on WebViewBuilderExtWindows.
  • In webview2/mod.rs, when the option is false, append ,CalculateNativeWinOcclusion to the default --disable-features string. No effect when with_additional_browser_args is used (documented), since that path is a full override.

Usage

let webview = WebViewBuilder::new()
    .with_url("https://example.com")
    .with_native_window_occlusion(false) // keep rendering while hidden/occluded
    .build(&window)?;

Notes

  • Windows-only; no-op on other platforms (the method only exists under #[cfg(windows)], like the other WebViewBuilderExtWindows options).
  • Type-checks for x86_64-pc-windows-gnu.
  • Added a covector changelog entry (minor).

Real-world validation: this is what made reliable multi-webview show/hide work in a Tauri app that pre-creates one hidden webview per service and swaps them — without it, the second-and-later webviews paint blank on first show.

Allow disabling WebView2's native window occlusion detection
(CalculateNativeWinOcclusion) so a webview keeps rendering while its
window is hidden or occluded. Webviews created while hidden otherwise
may never bring up their render surface and paint blank when first
shown, which breaks apps that pre-create and show/hide multiple
webviews (tabbed/multi-service shells).

Defaults to true (current WebView2 behavior); opt out via
WebViewBuilderExtWindows::with_native_window_occlusion(false).

Refs: tauri-apps/tauri#9798, MicrosoftEdge/WebView2Feedback#1077
@podheitor podheitor requested a review from a team as a code owner May 31, 2026 18:49
@Legend-Master Legend-Master added the ai-slop Low effort content, see https://github.com/tauri-apps/tauri?tab=contributing-ov-file#ai-tool-policy label Jun 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai-slop Low effort content, see https://github.com/tauri-apps/tauri?tab=contributing-ov-file#ai-tool-policy

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants