webview_plus #

A high-performance, cross-platform Flutter plugin that directly encapsulates native Webview components on all supported platforms.

Unlike other webview implementations that introduce complex virtualization layers, webview_plus embeds the underlying platform's native web view directly for maximum speed, memory efficiency, and standard compliance.

🚀 Platform Support Matrix #

✨ Features #

• True Native Embedding: Zero unnecessary wrappers. Uses WKWebview on Apple platforms, Chromium-based Webview2 on Windows, and WebKitGTK on Linux.
• Bi-directional JavaScript Bridge:
  • Execute Dart to JS via evaluateJavascript with automatic type unboxing (returns real Dart types like int, Map, List instead of raw strings).
  • Handle JS to Dart messages using either basic string streaming or full-featured promises via window.webview_plus.callHandler.
• Raw JS/CSS Injection Everywhere: injectJsData/injectCssData (one-off, via the controller) and WebviewWidget.initialCss (re-applied on every page load) are fully functional on all 5 platforms.
• Custom Native Context Menus: Fully customize text selection and long-press contextual menus on Android and iOS using native platform APIs (ActionMode & UIContextMenuConfiguration); disableContextMenu/disableLongPressContextMenuOnLinks additionally work natively on macOS (right-click).
• Comprehensive Lifecycle Callbacks: Track page loading starts, stops, navigation interception, and handle platform-specific web view errors.
• Advanced Asset & File System Access: Load URLs, bundle assets, or absolute file paths from the local device storage. allowFileAccessFromFileURLs/allowUniversalAccessFromFileURLs unlock local-file-to-local-file access on iOS/macOS.
• Scrollbar Theming (Windows/macOS/Linux): Custom track/thumb colors, width, and light/dark/auto/hidden modes via windowsScrollbarTheme, applied through native composition on Windows and injected ::-webkit-scrollbar CSS on macOS/Linux.
• Cache & Debug Utilities: WebviewCacheManager clears HTTP cache/cookies/all web data across every Webview in the app; WebviewPlusController.setWebContentsDebuggingEnabled() globally toggles remote DevTools/Web Inspector access.
• Android Rendering Performance: Defaults to Texture Layer Hybrid Composition (initSurfaceAndroidView) on API 23+, giving native-speed scrolling without the janky Flutter animations/transitions that plague classic Hybrid Composition. Automatically falls back to legacy modes on older devices.
• Android Preloading API: WebviewPlusPreloader lets you warm up the WebView engine and/or prefetch a URL into the shared HTTP cache before the user opens a webview screen, for a near-instant first paint. See Preloading & Faster First Load below.
• Automatic Script Injection: Declare a list of UserScripts in initialSettings.initialUserScripts to have them injected automatically into every page the webview loads (Android/iOS/macOS).
• Keyboard-Aware Layout Control: disableKeyboardResize stops the webview from shrinking when the on-screen keyboard appears, using native IME insets rather than a JS window.innerHeight workaround (Android/iOS).

🛠️ Quick Start #

import 'package:flutter/material.dart';
import 'package:webview_plus/webview_plus.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Webview Plus Example')),
        body: WebviewWidget(
          initialAsset: 'assets/index.html',
          onWebViewCreated: (controller) {
            print("Webview has been successfully instantiated.");
          },
          onMessageReceived: (message) {
            print("Received simple message from JS: $message");
          },
          onNavigationRequest: (url) {
            // Block specific navigation paths
            if (url.contains('blocked.com')) {
              print("Navigation to $url blocked!");
              return false; // Prevent navigation
            }
            return true; // Allow navigation
          },
        ),
      ),
    );
  }
}

📖 Deep Dive & Advanced Usage #

1. Bi-directional JavaScript Interaction #

Dart to JavaScript (with Native Types)

Forget manual JSON parsing. When evaluating JavaScript, the native bridge deserializes data into native Dart objects directly.

// Evaluate arithmetic or complex data structures
final dynamic result = await controller.evaluateJavascript('1 + 1'); 
print(result); // Outputs: 2 (as an int, not a String "2"!)

final Map<String, dynamic> user = await controller.evaluateJavascript('''
  (function() {
    return { name: "Noam", roles: ["admin", "developer"] };
  })()
''');

JavaScript to Dart Handlers (Promises & Callbacks)

Register namespaced handlers in Dart that return values or asynchronous futures directly back to JavaScript as native JS Promises.

Dart Implementation:

controller.addJavaScriptHandler(
  handlerName: 'calculateTax',
  callback: (args) async {
    // args maps exactly to parameters passed from JS
    double subtotal = args[0];
    double rate = args[1];
    return subtotal * rate; // Returned directly to JavaScript
  },
);

JavaScript Call:

// window.webview_plus is automatically injected into the page context
window.webview_plus.callHandler('calculateTax', 100.0, 0.20)
  .then(function(taxResult) {
    console.log("Tax computed by Dart: " + taxResult); // 20
  })
  .catch(function(error) {
    console.error("Error from Dart execution: ", error);
  });

2. Custom Native Context Menus (Android & iOS) #

You can strip down or add custom buttons to the native text selection action bar. This is handled deep within native platform architectures (ActionMode on Android and UIContextMenuConfiguration on iOS).

WebviewWidget(
  initialUrl: 'https://flutter.dev',
  contextMenuItems: [
    ContextMenuItem(
      id: 'search_lookup',
      name: 'Custom Lookup',
      action: (selectedText) {
        print("User highlighted and clicked lookup for: $selectedText");
      },
    ),
  ],
  initialSettings: const WebviewSettings(
    // Disable standard copy/cut/paste items if necessary
    disabledDefaultContextMenuItems: {
      DefaultContextMenuItem.cut,
      DefaultContextMenuItem.share, // If defined
    },
  ),
)

Note: Context menu customizations are silently ignored on desktop platforms (Windows, macOS, Linux) where traditional right-click drop-down menus operate without touch-selection bars.

3. Detailed Controller API Reference #

The WebviewPlusController exposes full programmatic control over the browser session:

⚡ Preloading & Faster First Load (Android) #

Android's WebView pays a one-time cost the first time it's ever instantiated in your app process — loading the Chromium engine, spinning up the sandboxed :webview_service process, etc. That cost is per process, not per instance, which means:

• Every webview after the first one in your app is already fast.
• The first webview the user ever opens takes the hit, right when they're waiting for it.

WebviewPlusPreloader gives you two independent, Android-only tools (silent no-ops on other platforms) to move that cost out of the user's way.

Engine warm-up #

Pre-builds blank WebView instances in the background so the first real WebviewWidget the user opens doesn't have to pay the engine init cost itself.

void main() {
  runApp(const MyApp());
  WidgetsBinding.instance.addPostFrameCallback((_) {
    WebviewPlusPreloader.warmUp(count: 1); // 1–5, call once after the first frame
  });
}

URL preloading #

Fetches a URL in the background using an invisible, disposable webview, filling the shared HTTP cache so the real webview that loads the same URL later gets it (partly or fully) from cache instead of the network.

// e.g. as soon as an article list is shown, warm the article the user
// is most likely to open next
WebviewPlusPreloader.preloadUrl('https://example.com/article/123');

Note: preloadUrl is best-effort — it relies entirely on the target server's HTTP caching headers (Cache-Control, ETag, etc.). If a resource is served with no-store or similar, preloading it simply has no measurable effect; it won't error, it just won't help for that resource.

4. Cache & Data Management (WebviewCacheManager) #

Independently of any [WebviewWidget] currently on screen, you can clear the data shared by every non-incognito Webview in your app:

// HTTP cache only (images, scripts, fetch/XHR responses...)
await WebviewCacheManager.clearCache();

// Cookies only
await WebviewCacheManager.clearCookies();

// Everything: cache, cookies, localStorage, IndexedDB, service workers...
await WebviewCacheManager.clearAllData();

Available on all 5 platforms. On Windows specifically, clearCache()/clearAllData() need at least one WebviewWidget to have already been created during the app session (the default WebView2 profile only exists from that point on) — call it after your first webview is created rather than at app launch.

5. Remote Debugging Toggle (WebviewPlusController.setWebContentsDebuggingEnabled) #

Unlike WebviewSettings.isInspectable (which only applies to the single instance it's set on), this toggles Chrome DevTools / Safari Web Inspector access for every Webview in the app, existing and future ones — handy to gate behind kDebugMode:

void main() {
  if (kDebugMode) {
    WebviewPlusController.setWebContentsDebuggingEnabled();
  }
  runApp(const MyApp());
}

6. Raw CSS Injected on Every Load (initialCss) #

WebviewWidget(
  initialUrl: 'https://example.com',
  initialCss: 'body { font-family: "Inter", sans-serif; }',
)

Unlike injectCssData on the controller (a one-off injection into whatever page is currently loaded), initialCss is re-applied automatically on every page load — including subsequent in-app navigations — on all 5 platforms.

⚙️ Configuration Options (WebviewSettings) #

Pass a custom WebviewSettings configuration object to fully customize behavior per-platform:

const WebviewSettings(
  javaScriptEnabled: true,
  domStorageEnabled: true,
  transparentBackground: true,
  isInspectable: true, // Enables Chrome DevTools / Safari Web Inspector debugging
)

Full Settings Parameter Grid #

Note on selectionHandleColor (Android): the CSS-based highlight (selectionTextColor) always applies reliably. The native handle tint is best-effort only — Android doesn't let a theme attribute be overridden with an arbitrary runtime value, only with resources compiled into the app. The dynamic color you pass drives the native handle tint only insofar as it matches the compiled @color/webview_plus_selection_handle_color resource shipped by the plugin.

Setup in MacOS #

Add this code in DebugProfile.entitlements and Release.entitlements to have acces in Internet in WebView and acces to all files in the computer.

<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.app-sandbox</key>
<false/>
<key>com.apple.security.files.user-selected.read-only</key>
<true/>

🐧 Setup on Linux #

In linux/my_application.cc, wrap the FlView in a GtkOverlay right after it's created, before gtk_widget_realize() and fl_register_plugins() are called:

FlView* view = fl_view_new(project);
GdkRGBA background_color;
gdk_rgba_parse(&background_color, "#000000");
fl_view_set_background_color(view, &background_color);
gtk_widget_set_hexpand(GTK_WIDGET(view), TRUE);
gtk_widget_set_vexpand(GTK_WIDGET(view), TRUE);
gtk_widget_show(GTK_WIDGET(view));

// --- Add this block ---
GtkWidget* overlay = gtk_overlay_new();
gtk_widget_set_hexpand(overlay, TRUE);
gtk_widget_set_vexpand(overlay, TRUE);
gtk_widget_show(overlay);
gtk_container_add(GTK_CONTAINER(overlay), GTK_WIDGET(view));
gtk_container_add(GTK_CONTAINER(window), overlay);
// --- instead of the original gtk_container_add(GTK_CONTAINER(window), GTK_WIDGET(view)); ---

g_signal_connect_swapped(view, "first-frame", G_CALLBACK(first_frame_cb), self);
gtk_widget_realize(GTK_WIDGET(view));

fl_register_plugins(FL_PLUGIN_REGISTRY(view));

That's the only change needed — the rest of my_application.cc (window/header bar setup, first_frame_cb, command line handling, etc.) stays exactly as generated by flutter create.

⚠️ Known Limitations & Architecture Caveats #

• Windows & Linux (Advanced Composition): Both Windows (Webview2) and Linux (WebKitWebView) use simplified window rendering strategies. True seamless stacking layouts (advanced transparency masks, multi-layered Flutter widgets directly over or under the web layer) may require unique configurations within the specific target OS shell runner.
• Linux Overlay Architecture: Since Linux lacks generic PlatformView composition hooks inside Flutter's engine core, this plugin binds a direct native GtkWidget on top of the Flutter window frame coordinates dynamically. Size, placement, and lifecycle updates are synchronised directly over global method channels. Requires a one-time edit to linux/my_application.cc — see Setup on Linux.
• Web Iframes Constraints: onNavigationRequest is fully dependable only when loading content with matching origins (such as local bundled assets). Standard web browser security frames block cross-origin navigation interceptions on independent <iframe> nodes.
• Android Composition Mode Detection: The plugin queries the device's API level asynchronously on first use and optimistically assumes API 23+ (Texture Layer Hybrid Composition) while that check is in flight — accurate for the vast majority of active devices. On the rare API < 23 device, the widget seamlessly rebuilds with the correct legacy mode once the check resolves, which may cause a single, barely noticeable extra rebuild the very first time a webview is shown in the app's lifetime.
• preloadUrl Has No Effect on Uncacheable Content: Preloading only helps for resources the server allows to be cached (see Preloading & Faster First Load).
• WebviewCacheManager.clearCache()/clearAllData() on Windows: need at least one WebviewWidget to have already been created during the app session, since the default WebView2 profile they operate on doesn't otherwise exist yet.
• WebviewPlusController.setWebContentsDebuggingEnabled() on iOS/macOS: best-effort — relies on WKWebView.isInspectable, only available on iOS 16.4+/macOS 13.3+. On older OS versions it's a silent no-op; use WebviewSettings.isInspectable at webview creation time instead.
• bounces / allowsInlineMediaPlayback: iOS-only. WKWebView on macOS never forces fullscreen media playback and doesn't expose a public bounce-physics API, so neither setting has a macOS equivalent.

📝 Example #

For a complete working deployment showcase showcasing full bidirectional communication pipelines, layout changes, and asset mounting routines, review the detailed example/lib/main.dart source file.

📄 License #

Developed by Noam. Licensed under standard project conditions.