Hosting native Android views in your Flutter app with Platform Views

Platform views allow you to embed native views in a Flutter app, so you can apply transforms, clips, and opacity to the native view from Dart.

This allows you, for example, to use the native Google Maps from the Android SDK directly inside your Flutter app.

Platform Views on Android have several implementations. They come with tradeoffs both in terms of performance and fidelity.

The following matrix summarizes the different implementations and their trade-offs:

Platform Views are rendered as they are normally. Flutter content is rendered into a texture. SurfaceFlinger composes the Flutter content and the platform views.

HCPP is the latest hybrid composition strategy, designed to solve compositing performance and synchronization issues seen in the original Hybrid Composition mode. It is currently available as an opt-in feature.

• Android API 34 or later: Required for native transaction synchronization capabilities.
• Vulkan rendering: The device must be capable of rendering with Vulkan. Required for Impeller to be enabled.

If these requirements are not met on the end-user device, Flutter will automatically fall back to the existing platform view strategy configured for the app.

Because HCPP acts as a global upgrade for how platform views are backed, it's enabled through configuration rather than standard Dart initialization methods (initAndroidView, and so on).

You can enable HCPP using one of the following methods:

1. Command line flag (run/test): Pass the --enable-hcpp flag to your flutter run or flutter test command:

   $ flutter run --enable-hcpp
   

   content_copy

2. AndroidManifest.xml: Include a <meta-data> tag inside the <application> block of your AndroidManifest.xml:

   xml

   <meta-data
       android:name="io.flutter.embedding.android.EnableHcpp"
       android:value="true" />
   

   content_copy

• Complex overlay stacking: Transparent platform views won't display correctly in layout stacks structured as: Flutter canvas -> Platform View -> Overlay -> Transparent Platform View, when all four of these layers intersect.

Platform Views are rendered into a texture. Flutter draws the platform views (using the texture). Flutter content is rendered directly into a Surface.

This approach provides:

• good performance for Android Views
• good performance for Flutter rendering
• all transformations work correctly

However, this approach might cause:

• jankiness on quick scrolling (such as a web view)
• broken accessibility for SurfaceViews
• broken text magnification unless Flutter is rendered into a TextureView

To create a platform view on Android, use the following steps. First, on the Dart side, create a Widget and add one of the following build implementations depending on your chosen strategy.

In your Dart file, for example native_view_example.dart, use the following instructions:

1. Add the following imports:

   dart

   import 'package:flutter/foundation.dart';
   import 'package:flutter/gestures.dart';
   import 'package:flutter/material.dart';
   import 'package:flutter/rendering.dart';
   import 'package:flutter/services.dart';
   

   content_copy

2. Implement a build method:

   dart

   Widget build(BuildContext context) {
     // This is used in the platform side to register the view.
     const String viewType = '<platform-view-type>';
     // Pass parameters to the platform side.
     const Map<String, dynamic> creationParams = <String, dynamic>{};
   ​
     return PlatformViewLink(
       viewType: viewType,
       surfaceFactory: (context, controller) {
         return AndroidViewSurface(
           controller: controller as AndroidViewController,
           gestureRecognizers: const <Factory<OneSequenceGestureRecognizer>>{},
           hitTestBehavior: PlatformViewHitTestBehavior.opaque,
         );
       },
       onCreatePlatformView: (params) {
         return PlatformViewsService.initSurfaceAndroidView(
             id: params.id,
             viewType: viewType,
             layoutDirection: TextDirection.ltr,
             creationParams: creationParams,
             creationParamsCodec: const StandardMessageCodec(),
             onFocus: () {
               params.onFocusChanged(true);
             },
           )
           ..addOnPlatformViewCreatedListener(params.onPlatformViewCreated)
           ..create();
       },
     );
   }
   

   content_copy

For more information, visit the following API docs:

• PlatformViewLink
• AndroidViewSurface
• PlatformViewsService

In your Dart file, for example native_view_example.dart, use the following instructions:

1. Add the following imports:

   dart

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

   content_copy

2. Implement a build method:

   dart

   Widget build(BuildContext context) {
     // This is used in the platform side to register the view.
     const String viewType = '<platform-view-type>';
     // Pass parameters to the platform side.
     final Map<String, dynamic> creationParams = <String, dynamic>{};
   ​
     return AndroidView(
       viewType: viewType,
       layoutDirection: TextDirection.ltr,
       creationParams: creationParams,
       creationParamsCodec: const StandardMessageCodec(),
     );
   }
   

   content_copy

For more information, visit the AndroidView API page.

On the platform side, use the standard io.flutter.plugin.platform package in either Kotlin or Java:

package dev.flutter.example
​
import android.content.Context
import android.graphics.Color
import android.view.View
import android.widget.TextView
import io.flutter.plugin.platform.PlatformView
​
internal class NativeView(context: Context, id: Int, creationParams: Map<String?, Any?>?) : PlatformView {
    private val textView: TextView
​
    override fun getView(): View {
        return textView
    }
​
    override fun dispose() {}
​
    init {
        textView = TextView(context)
        textView.textSize = 72f
        textView.setBackgroundColor(Color.rgb(255, 255, 255))
        textView.text = "Rendered on a native Android view (id: $id)"
    }
}

package dev.flutter.example
​
import android.content.Context
import io.flutter.plugin.common.StandardMessageCodec
import io.flutter.plugin.platform.PlatformView
import io.flutter.plugin.platform.PlatformViewFactory
​
class NativeViewFactory : PlatformViewFactory(StandardMessageCodec.INSTANCE) {
    override fun create(context: Context, viewId: Int, args: Any?): PlatformView {
        val creationParams = args as Map<String?, Any?>?
        return NativeView(context, viewId, creationParams)
    }
}

package dev.flutter.example
​
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
​
class MainActivity : FlutterActivity() {
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)
        flutterEngine
                .platformViewsController
                .registry
                .registerViewFactory("<platform-view-type>",
                                      NativeViewFactory())
    }
}

package dev.flutter.plugin.example
​
import io.flutter.embedding.engine.plugins.FlutterPlugin
import io.flutter.embedding.engine.plugins.FlutterPlugin.FlutterPluginBinding
​
class PlatformViewPlugin : FlutterPlugin {
    override fun onAttachedToEngine(binding: FlutterPluginBinding) {
        binding
                .platformViewRegistry
                .registerViewFactory("<platform-view-type>", NativeViewFactory())
    }
​
    override fun onDetachedFromEngine(binding: FlutterPluginBinding) {}
}

package dev.flutter.example;
​
import android.content.Context;
import android.graphics.Color;
import android.view.View;
import android.widget.TextView;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import io.flutter.plugin.platform.PlatformView;
import java.util.Map;
​
class NativeView implements PlatformView {
   @NonNull private final TextView textView;
​
    NativeView(@NonNull Context context, int id, @Nullable Map<String, Object> creationParams) {
        textView = new TextView(context);
        textView.setTextSize(72);
        textView.setBackgroundColor(Color.rgb(255, 255, 255));
        textView.setText("Rendered on a native Android view (id: " + id + ")");
    }
​
    @NonNull
    @Override
    public View getView() {
        return textView;
    }
​
    @Override
    public void dispose() {}
}

package dev.flutter.example;
​
import android.content.Context;
import androidx.annotation.Nullable;
import androidx.annotation.NonNull;
import io.flutter.plugin.common.StandardMessageCodec;
import io.flutter.plugin.platform.PlatformView;
import io.flutter.plugin.platform.PlatformViewFactory;
import java.util.Map;
​
class NativeViewFactory extends PlatformViewFactory {
​
  NativeViewFactory() {
    super(StandardMessageCodec.INSTANCE);
  }
​
  @NonNull
  @Override
  public PlatformView create(@NonNull Context context, int id, @Nullable Object args) {
    final Map<String, Object> creationParams = (Map<String, Object>) args;
    return new NativeView(context, id, creationParams);
  }
}

package dev.flutter.example;
​
import androidx.annotation.NonNull;
import io.flutter.embedding.android.FlutterActivity;
import io.flutter.embedding.engine.FlutterEngine;
​
public class MainActivity extends FlutterActivity {
    @Override
    public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine) {
        flutterEngine
            .getPlatformViewsController()
            .getRegistry()
            .registerViewFactory("<platform-view-type>", new NativeViewFactory());
    }
}

package dev.flutter.plugin.example;
​
import androidx.annotation.NonNull;
import io.flutter.embedding.engine.plugins.FlutterPlugin;
​
public class PlatformViewPlugin implements FlutterPlugin {
  @Override
  public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) {
    binding
        .getPlatformViewRegistry()
        .registerViewFactory("<platform-view-type>", new NativeViewFactory());
  }
​
  @Override
  public void onDetachedFromEngine(@NonNull FlutterPluginBinding binding) {}
}

For more information, visit the API docs for:

• FlutterPlugin
• PlatformViewRegistry
• PlatformViewFactory
• PlatformView

Finally, modify your build.gradle file to require one of the minimal Android SDK versions:

android {
    defaultConfig {
        minSdk = 19 // if using hybrid composition
        minSdk = 20 // if using virtual display.
    }
}

Certain Android Views don't invalidate themselves when their content changes. Some examples include SurfaceView and SurfaceTexture. When your Platform View includes these views, you must manually invalidate it after it has been drawn (or, more specifically, after the swap chain is flipped). Invalidate the view by calling invalidate on it or on one of its parents.

Check out the existing Platform View issues on GitHub.

Platform views in Flutter come with performance trade-offs.

In a typical Flutter app, the Flutter UI is composed on a dedicated raster thread, while platform code runs on the UI/platform thread. This separation keeps Flutter rendering fast and fluid.

However, when a platform view is rendered on Android using hybrid composition, Flutter merges the raster and UI threads into a single thread to ensure correct synchronization between the native Android views and the Flutter canvas. Because of this thread merging, rendering complex Flutter widgets alongside a platform view can compete with OS messages and plugin interactions, potentially causing lower application FPS and frame drops.

Also, prior to Android 10, hybrid composition copied each Flutter frame out of the graphic memory into main memory, and then copied it back to a GPU texture. As this copy happens per frame, the performance of the entire Flutter UI might be impacted. In Android 10 or above, the graphics memory is copied only once.

Hybrid Composition++ (HCPP) minimizes this overhead by using native transaction synchronization on supported devices (Android API 34+ with Vulkan), allowing superior performance without the heavy costs of original hybrid composition.

Virtual display, on the other hand, makes each pixel of the native view flow through additional intermediate graphic buffers, which cost graphic memory and drawing performance. This can cause jank during high-frequency updates like fast scrolling.

For complex cases, there are some techniques that can be used to mitigate these issues.

For example, you can use a placeholder texture while an animation is happening in Dart. In other words, if an animation is slow while a platform view is rendered, then consider taking a screenshot of the native view and rendering it as a texture.

For more information, visit the following API pages:

• TextureLayer
• TextureRegistry
• FlutterTextureRegistry
• FlutterImageView