flutter-embedding-native-views

Original：🇺🇸 English

Translated

Embeds native Android, iOS, or macOS views into a Flutter app. Use when integrating complex native components like maps or web views.

5installs

Sourceflutter/skills

Added on2026-03-13

NPX Install

npx skill4agent add flutter/skills flutter-embedding-native-views

SKILL.md Content

View Translation Comparison →

Integrating Platform Views and Web Content

Platform Views Architecture
Web Embedding Architecture
Workflow: Implementing Android Platform Views
Workflow: Implementing iOS Platform Views
Workflow: Embedding Flutter in Web Applications
Examples

Platform Views Architecture

Platform Views allow embedding native views (Android, iOS, macOS) directly into a Flutter application, enabling the application of transforms, clips, and opacity from Dart.

Android Implementations (API 23+)

Choose the appropriate implementation based on your performance and fidelity requirements:

Hybrid Composition: Renders Flutter content into a texture and uses
```
SurfaceFlinger
```
to compose both.
- Pros: Best performance and fidelity for Android views.
- Cons: Lowers overall application FPS. Certain Flutter widget transformations will not work.
Texture Layer (Texture Layer Hybrid Composition): Renders Platform Views into a texture. Flutter draws them via the texture and renders its own content directly into a Surface.
- Pros: Best performance for Flutter rendering. All transformations work correctly.
- Cons: Quick scrolling (e.g., WebViews) can be janky.
```
SurfaceView
```
  is problematic (breaks accessibility). Text magnifiers break unless Flutter is rendered into a
```
TextureView
```
  .

iOS & macOS Implementations

iOS: Uses Hybrid Composition exclusively. The native
```
UIView
```
is appended to the view hierarchy.
- Limitations:
```
ShaderMask
```
  and
```
ColorFiltered
```
  widgets are not supported.
```
BackdropFilter
```
  has composition limitations.
macOS: Uses Hybrid Composition (
```
NSView
```
).
- Limitations: Not fully functional in current releases (e.g., gesture support is unavailable).

Performance Mitigation

Mitigate performance drops during complex Dart animations by rendering a screenshot of the native view as a placeholder texture while the animation runs.

Web Embedding Architecture

Embed Flutter into existing web applications (Vanilla JS, React, Angular, etc.) using either Full Page mode or Embedded (Multi-view) mode.

Full Page Mode: Flutter takes over the entire browser window. Use an
```
iframe
```
if you need to constrain the Flutter app without modifying the Flutter bootstrap process.
Embedded Mode (Multi-view): Render Flutter into specific HTML elements (
```
div
```
s). Requires
```
multiViewEnabled: true
```
during engine initialization.
- Manage views from JavaScript using
```
app.addView()
```
  and
```
app.removeView()
```
  .
- In Dart, replace
```
runApp
```
  with
```
runWidget
```
  .
- Manage the dynamic list of views using
```
WidgetsBinding.instance.platformDispatcher.views
```
  and render them using
```
ViewCollection
```
  and
```
View
```
  widgets.

Workflow: Implementing Android Platform Views

Follow this sequential workflow to implement a Platform View on Android.

Task Progress:

1. Determine the composition mode (Hybrid vs. Texture Layer).
2. Implement the Dart widget.
3. Implement the native Android View and Factory.
4. Register the Platform View in the Android host.
5. Run validator -> review rendering -> fix manual invalidation issues.

1. Dart Implementation

If using Hybrid Composition, use

PlatformViewLink

AndroidViewSurface

, and

PlatformViewsService.initSurfaceAndroidView

. If using Texture Layer, use the

AndroidView

widget.

2. Native Implementation

Create a class implementing

io.flutter.plugin.platform.PlatformView

that returns your native

android.view.View

. Create a factory extending

PlatformViewFactory

to instantiate your view.

3. Registration

MainActivity.kt

(or plugin) using

flutterEngine.platformViewsController.registry.registerViewFactory

Note: If your native view uses
SurfaceView
or
SurfaceTexture
, manually call
invalidate
on the View or its parent when content changes, as they do not invalidate themselves automatically.

Workflow: Implementing iOS Platform Views

Follow this sequential workflow to implement a Platform View on iOS.

Task Progress:

1. Implement the Dart widget using
```
UiKitView
```
.
2. Implement the native iOS View (
```
FlutterPlatformView
```
) and Factory (
```
FlutterPlatformViewFactory
```
).
3. Register the Platform View in
```
AppDelegate.swift
```
or the plugin registrar.
4. Run validator -> review composition limitations -> fix unsupported filters.

Workflow: Embedding Flutter in Web Applications

Follow this sequential workflow to embed Flutter into an existing web DOM.

Task Progress:

1. Update
```
flutter_bootstrap.js
```
to enable multi-view.
2. Update
```
main.dart
```
to use
```
runWidget
```
and
```
ViewCollection
```
.
3. Implement JavaScript logic to add/remove host elements.
4. Run validator -> review view constraints -> fix CSS conflicts.

1. JavaScript Configuration

flutter_bootstrap.js

, initialize the engine with

multiViewEnabled: true

. Use the returned

app

object to add views:

app.addView({ hostElement: document.getElementById('my-div') })

2. Dart Configuration

Replace

runApp()

with

runWidget()

. Create a root widget that listens to

WidgetsBindingObserver.didChangeMetrics

. Map over

WidgetsBinding.instance.platformDispatcher.views

to create a

View

widget for each attached

FlutterView

, and wrap them all in a

ViewCollection

Examples

Example: Android Texture Layer (Dart)

dart

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

class NativeAndroidView extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    const String viewType = 'my_native_view';
    final Map<String, dynamic> creationParams = <String, dynamic>{};

    return AndroidView(
      viewType: viewType,
      layoutDirection: TextDirection.ltr,
      creationParams: creationParams,
      creationParamsCodec: const StandardMessageCodec(),
    );
  }
}

Example: Web Multi-View Initialization (JavaScript)

javascript

_flutter.loader.load({
  onEntrypointLoaded: async function(engineInitializer) {
    let engine = await engineInitializer.initializeEngine({
      multiViewEnabled: true,
    });
    let app = await engine.runApp();
    
    // Add a view to a specific DOM element
    let viewId = app.addView({
      hostElement: document.querySelector('#flutter-host-container'),
      initialData: { customData: 'Hello from JS' }
    });
  }
});

Example: Web Multi-View Root Widget (Dart)

dart

import 'dart:ui' show FlutterView;
import 'package:flutter/widgets.dart';

void main() {
  runWidget(MultiViewApp(viewBuilder: (context) => const MyEmbeddedWidget()));
}

class MultiViewApp extends StatefulWidget {
  final WidgetBuilder viewBuilder;
  const MultiViewApp({super.key, required this.viewBuilder});

  @override
  State<MultiViewApp> createState() => _MultiViewAppState();
}

class _MultiViewAppState extends State<MultiViewApp> with WidgetsBindingObserver {
  Map<Object, Widget> _views = {};

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _updateViews();
  }

  @override
  void didChangeMetrics() => _updateViews();

  void _updateViews() {
    final newViews = <Object, Widget>{};
    for (final FlutterView view in WidgetsBinding.instance.platformDispatcher.views) {
      newViews[view.viewId] = _views[view.viewId] ?? View(
        view: view,
        child: Builder(builder: widget.viewBuilder),
      );
    }
    setState(() => _views = newViews);
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return ViewCollection(views: _views.values.toList(growable: false));
  }
}

Integrating Platform Views and Web Content

Platform Views Architecture
Web Embedding Architecture
Workflow: Implementing Android Platform Views
Workflow: Implementing iOS Platform Views
Workflow: Embedding Flutter in Web Applications
Examples

Platform Views Architecture

Platform Views allow embedding native views (Android, iOS, macOS) directly into a Flutter application, enabling the application of transforms, clips, and opacity from Dart.

Android Implementations (API 23+)

Choose the appropriate implementation based on your performance and fidelity requirements:

Hybrid Composition: Renders Flutter content into a texture and uses
```
SurfaceFlinger
```
to compose both.
- Pros: Best performance and fidelity for Android views.
- Cons: Lowers overall application FPS. Certain Flutter widget transformations will not work.
Texture Layer (Texture Layer Hybrid Composition): Renders Platform Views into a texture. Flutter draws them via the texture and renders its own content directly into a Surface.
- Pros: Best performance for Flutter rendering. All transformations work correctly.
- Cons: Quick scrolling (e.g., WebViews) can be janky.
```
SurfaceView
```
  is problematic (breaks accessibility). Text magnifiers break unless Flutter is rendered into a
```
TextureView
```
  .

iOS & macOS Implementations

iOS: Uses Hybrid Composition exclusively. The native
```
UIView
```
is appended to the view hierarchy.
- Limitations:
```
ShaderMask
```
  and
```
ColorFiltered
```
  widgets are not supported.
```
BackdropFilter
```
  has composition limitations.
macOS: Uses Hybrid Composition (
```
NSView
```
).
- Limitations: Not fully functional in current releases (e.g., gesture support is unavailable).

Performance Mitigation

Mitigate performance drops during complex Dart animations by rendering a screenshot of the native view as a placeholder texture while the animation runs.

Web Embedding Architecture

Embed Flutter into existing web applications (Vanilla JS, React, Angular, etc.) using either Full Page mode or Embedded (Multi-view) mode.

Full Page Mode: Flutter takes over the entire browser window. Use an
```
iframe
```
if you need to constrain the Flutter app without modifying the Flutter bootstrap process.
Embedded Mode (Multi-view): Render Flutter into specific HTML elements (
```
div
```
s). Requires
```
multiViewEnabled: true
```
during engine initialization.
- Manage views from JavaScript using
```
app.addView()
```
  and
```
app.removeView()
```
  .
- In Dart, replace
```
runApp
```
  with
```
runWidget
```
  .
- Manage the dynamic list of views using
```
WidgetsBinding.instance.platformDispatcher.views
```
  and render them using
```
ViewCollection
```
  and
```
View
```
  widgets.

Workflow: Implementing Android Platform Views

Follow this sequential workflow to implement a Platform View on Android.

Task Progress:

1. Determine the composition mode (Hybrid vs. Texture Layer).
2. Implement the Dart widget.
3. Implement the native Android View and Factory.
4. Register the Platform View in the Android host.
5. Run validator -> review rendering -> fix manual invalidation issues.

1. Dart Implementation

If using Hybrid Composition, use

PlatformViewLink

AndroidViewSurface

, and

PlatformViewsService.initSurfaceAndroidView

. If using Texture Layer, use the

AndroidView

widget.

2. Native Implementation

Create a class implementing

io.flutter.plugin.platform.PlatformView

that returns your native

android.view.View

. Create a factory extending

PlatformViewFactory

to instantiate your view.

3. Registration

MainActivity.kt

(or plugin) using

flutterEngine.platformViewsController.registry.registerViewFactory

Note: If your native view uses
SurfaceView
or
SurfaceTexture
, manually call
invalidate
on the View or its parent when content changes, as they do not invalidate themselves automatically.

Workflow: Implementing iOS Platform Views

Follow this sequential workflow to implement a Platform View on iOS.

Task Progress:

1. Implement the Dart widget using
```
UiKitView
```
.
2. Implement the native iOS View (
```
FlutterPlatformView
```
) and Factory (
```
FlutterPlatformViewFactory
```
).
3. Register the Platform View in
```
AppDelegate.swift
```
or the plugin registrar.
4. Run validator -> review composition limitations -> fix unsupported filters.

Workflow: Embedding Flutter in Web Applications

Follow this sequential workflow to embed Flutter into an existing web DOM.

Task Progress:

1. Update
```
flutter_bootstrap.js
```
to enable multi-view.
2. Update
```
main.dart
```
to use
```
runWidget
```
and
```
ViewCollection
```
.
3. Implement JavaScript logic to add/remove host elements.
4. Run validator -> review view constraints -> fix CSS conflicts.

1. JavaScript Configuration

flutter_bootstrap.js

, initialize the engine with

multiViewEnabled: true

. Use the returned

app

object to add views:

app.addView({ hostElement: document.getElementById('my-div') })

2. Dart Configuration

Replace

runApp()

with

runWidget()

. Create a root widget that listens to

WidgetsBindingObserver.didChangeMetrics

. Map over

WidgetsBinding.instance.platformDispatcher.views

to create a

View

widget for each attached

FlutterView

, and wrap them all in a

ViewCollection

Examples

Example: Android Texture Layer (Dart)

dart

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

class NativeAndroidView extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    const String viewType = 'my_native_view';
    final Map<String, dynamic> creationParams = <String, dynamic>{};

    return AndroidView(
      viewType: viewType,
      layoutDirection: TextDirection.ltr,
      creationParams: creationParams,
      creationParamsCodec: const StandardMessageCodec(),
    );
  }
}

Example: Web Multi-View Initialization (JavaScript)

javascript

_flutter.loader.load({
  onEntrypointLoaded: async function(engineInitializer) {
    let engine = await engineInitializer.initializeEngine({
      multiViewEnabled: true,
    });
    let app = await engine.runApp();
    
    // Add a view to a specific DOM element
    let viewId = app.addView({
      hostElement: document.querySelector('#flutter-host-container'),
      initialData: { customData: 'Hello from JS' }
    });
  }
});

Example: Web Multi-View Root Widget (Dart)

dart

import 'dart:ui' show FlutterView;
import 'package:flutter/widgets.dart';

void main() {
  runWidget(MultiViewApp(viewBuilder: (context) => const MyEmbeddedWidget()));
}

class MultiViewApp extends StatefulWidget {
  final WidgetBuilder viewBuilder;
  const MultiViewApp({super.key, required this.viewBuilder});

  @override
  State<MultiViewApp> createState() => _MultiViewAppState();
}

class _MultiViewAppState extends State<MultiViewApp> with WidgetsBindingObserver {
  Map<Object, Widget> _views = {};

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _updateViews();
  }

  @override
  void didChangeMetrics() => _updateViews();

  void _updateViews() {
    final newViews = <Object, Widget>{};
    for (final FlutterView view in WidgetsBinding.instance.platformDispatcher.views) {
      newViews[view.viewId] = _views[view.viewId] ?? View(
        view: view,
        child: Builder(builder: widget.viewBuilder),
      );
    }
    setState(() => _views = newViews);
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return ViewCollection(views: _views.values.toList(growable: false));
  }
}

flutter-embedding-native-views

NPX Install

Tags

SKILL.md Content

Integrating Platform Views and Web Content

Contents

Platform Views Architecture

Android Implementations (API 23+)

iOS & macOS Implementations

Performance Mitigation

Web Embedding Architecture

Workflow: Implementing Android Platform Views

1. Dart Implementation

2. Native Implementation

3. Registration

Workflow: Implementing iOS Platform Views

Workflow: Embedding Flutter in Web Applications

1. JavaScript Configuration

2. Dart Configuration

Examples

Example: Android Texture Layer (Dart)

Example: Web Multi-View Initialization (JavaScript)

Example: Web Multi-View Root Widget (Dart)

flutter-embedding-native-views

NPX Install

Tags

SKILL.md Content

Integrating Platform Views and Web Content

Contents

Platform Views Architecture

Android Implementations (API 23+)

iOS & macOS Implementations

Performance Mitigation

Web Embedding Architecture

Workflow: Implementing Android Platform Views

1. Dart Implementation

2. Native Implementation

3. Registration

Workflow: Implementing iOS Platform Views

Workflow: Embedding Flutter in Web Applications

1. JavaScript Configuration

2. Dart Configuration

Examples

Example: Android Texture Layer (Dart)

Example: Web Multi-View Initialization (JavaScript)

Example: Web Multi-View Root Widget (Dart)