Embedder in Flutter

What is an embedder in Flutter?

The Flutter embedder is the platform-specific code that starts the Flutter engine and connects it to the operating system. It is the layer that allows Flutter to run on Android, iOS, desktop systems, or custom devices.

Simply put: the embedder is the native code that launches Flutter and hosts its rendering surface.

Why does the embedder matter in Flutter app development?

Even if you never modify it, the embedder affects:

• app startup time
• input latency
• platform behavior differences
• how plugins and platform channels work

When Flutter behaves differently on Android and iOS, the reason is often in the embedder, not in Dart code.

Where is the embedder in a Flutter project?

For most developers, the embedder already exists in their project as native code:

• Android: android/app/src/main/.../MainActivity.kt
• iOS: ios/Runner/AppDelegate.swift (and SceneDelegate on newer iOS versions)

These files:

• Create the Flutter engine.
• Attach it to a native window.
• Start rendering Flutter UI.

This is the embedder layer you interact with indirectly.

How does the Flutter embedder work?

Flutter does not translate widgets into native UI components.

The embedder follows a simple rule: Input → Engine → Pixels

• The embedder provides a surface (window, texture, canvas).
• It forwards input events (touch, keyboard, mouse) to the engine.
• The Flutter engine renders pixels using Skia.
• The embedder displays those pixels on screen.

A Container is never converted into a LinearLayout or UIView.

When do you need to care about the embedder?

You should think about the embedder when:

• Embedding Flutter into an existing native app (add-to-app).
• Debugging startup or input issues.
• Writing advanced plugins with native lifecycle hooks.
• Targeting non-standard platforms.

For typical apps, the default embedder is enough.

When not to touch the embedder?

Do not modify the embedder when:

• Solving layout or UI issues.
• Optimizing widget rebuilds.
• Fixing state management bugs.
• Working purely in Dart.

Most problems belong to the framework layer, not the embedder.

Flutter Embedder API

The Flutter Embedder API is a low-level C-based API used to create custom embedders. It allows a host app to:

• Start and stop a Flutter engine.
• Send input events.
• Manage textures.
• Handle platform messages.

Official platforms use it internally, but it is also used for custom environments.

Custom embedders and portability

Because the embedder is replaceable, Flutter can run on:

• embedded Linux
• Raspberry Pi
• automotive systems
• smart TVs

All that is needed is native code that opens a window, forwards input, and hosts the Flutter engine.

Relation to platform channels

The embedder is where platform channels terminate on the native side. It initializes plugins and enables communication between Dart and native APIs.

Common mistakes to avoid

• Thinking Flutter widgets map to native UI components.
• Trying to fix UI bugs by editing native files.
• Confusing plugins with embedder responsibilities.
• Overestimating how often the embedder should be touched.