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.
• Custom Native Context Menus: Fully customize text selection and long-press contextual menus on Android and iOS using native platform APIs (ActionMode & UIContextMenuConfiguration).
• 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.

🛠️ 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).

WebviewPlus(
  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:

⚙️ 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 #

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/>

⚠️ 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.
• 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.

📝 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.