Choosing PlatformView Implementations for Flutter Hybrid Development on Android

This is the fourth article in the "Flutter Engineering Framework Selection" series, aimed at beginners who need a quick guide to choose functional modules when creating a Flutter project.

This piece focuses on technology selection for hybrid development, highlighting common pitfalls and explaining why this technical‑focused episode is necessary.

Hybrid development in Flutter is challenging because Flutter uses its own rendering engine, which separates Flutter widgets from the platform view hierarchy, making integration of native controls complex.

There are two hybrid approaches: embedding native platform controls inside Flutter via PlatformView , and embedding Flutter into a native app using the add-to-app method. This article concentrates on the Android side of PlatformView selection.

PlatformView

On Android, three official PlatformView implementations exist:

VirtualDisplays : creates a virtual display area, renders content to a Surface , and synchronises the texture to the Flutter engine. The native view is not rendered directly in the widget tree.

HybridComposition : adds the native view to the hierarchy with addView and stacks it using FlutterImageView . The native view renders at its actual position, preserving native behaviour but with higher performance cost.

TextureLayer : wraps the native view with a PlatformViewWrapper , replaces the Canvas to extract the texture onto a specific Surface . The view is not in the render tree but can intercept events via its parent.

These implementations have version‑dependent constraints:

Before Flutter 1.2 only VirtualDisplays was available.

Before Flutter 3.0 you could use VirtualDisplays and HybridComposition .

Before Flutter 3.3 you could use TextureLayer and HybridComposition .

From Flutter 3.3 onward all three— VirtualDisplays , TextureLayer , and HybridComposition —are usable, but TextureLayer requires a minimum SDK of 23 and may fall back to VirtualDisplays for SurfaceView scenarios.

Because VirtualDisplays suffers from touch and keyboard issues, HybridComposition was introduced to solve those problems by stacking native views. However, HybridComposition can cause list jitter and rendering thread desynchronisation, so VirtualDisplays remains as a fallback.

When using the webview_flutter plugin, the default implementation switched from AndroidWebView ( VirtualDisplays ) to SurfaceAndroidWebView ( HybridComposition ) because the latter handles WebView scenarios better. You can explicitly set the implementation with the following code:

if (Platform.isAndroid) WebView.platform = SurfaceAndroidWebView();

Map SDKs also use PlatformView but differ in their chosen implementation:

Gaode (amap_flutter_map) uses AndroidView with VirtualDisplays before Flutter 3.0 and TextureLayer after.

Huawei (huawei_map) adopts HybridComposition and requires explicit initialization via initExpensiveAndroidView .

Baidu (flutter_baidu_mapapi_map) uses AndroidView with both TextureView and SurfaceView , leading to different combinations of VirtualDisplays and TextureLayer depending on the view type.

Key take‑aways for the three PlatformView methods:

VirtualDisplays : reliable “old‑timer”, extracts texture via a virtual display; may have gesture/keyboard issues; suitable for simple widgets; unavailable in Flutter 3.0.

HybridComposition : introduced after Flutter 1.2, adds native view with addView ; preserves native behaviour but incurs higher performance cost; requires initExpensiveAndroidView from Flutter 3.0 onward.

TextureLayer : appears in Flutter 3.0, hooks the native view’s Canvas to extract texture; needs min SDK 23; works well except when the native view is a SurfaceView , in which case it falls back to VirtualDisplays .

Future Flutter releases will likely adjust this logic again, but changes may not be highlighted in release notes.

Finally, note the commercial licensing of domestic map SDKs in China: providers charge a minimum of 50,000 CNY for commercial use, and applications must hold proper mapping qualifications. Huawei’s map service does not require a commercial license but needs HMS integration.

Regulatory note: Apps using internet map services must obtain the required mapping qualification certificates and display them prominently, or provide a cooperation agreement with the third‑party map provider.

In summary, selecting the right PlatformView implementation depends on Flutter version, target Android SDK, performance requirements, and the specific native view (e.g., WebView, MapView). Understanding these trade‑offs helps avoid “pitfalls” during hybrid development.