From a647f9ee49adce5f99f2fd1ea6c216d0f8711510 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Tue, 18 Aug 2026 09:59:58 -0700 Subject: [PATCH 1/3] Add iframe vs DOM embedding comparison --- .../web/embedding-flutter-web.md | 92 +++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md b/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md index 2007039155..97a390d5a4 100644 --- a/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md +++ b/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md @@ -55,6 +55,55 @@ check out the [Inline Frame element][] docs on MDN. [Inline Frame element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe +### Compare `iframe` and direct DOM embedding {: #compare-iframe-and-dom-embedding } + +When integrating Flutter into an existing web application, +choose between `iframe` embedding and direct DOM embedding +(`hostElement` or multi-view) +based on your isolation, performance, and communication requirements: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Featureiframe embeddingDirect DOM embedding (hostElement / multi-view)
Isolation & sandboxingFull browser sandboxing with separate JS global scope, DOM tree, and CSS styles.Shares the same DOM tree, JavaScript context, and CSS styles with the host page.
Memory & engine instancesEach iframe initializes its own Flutter engine, WebAssembly/JS runtime, and memory heap.A single Flutter engine instance and memory heap can manage one or more views.
JavaScript interopCommunication requires asynchronous messaging (such as postMessage).Direct synchronous communication using package:web and dart:js_interop.
Styling & layoutIndependent frame isolated from host page CSS.Direct integration into host page CSS layout (such as flexbox and grid).
State sharingState must be synchronized across window boundaries.Direct state sharing in Dart across all attached views.
Best forThird-party widgets, untrusted content, isolated micro-frontends, or simple drop-in embeds.Embedded UI components in existing web apps, multi-view dashboards, and tight host-app integration.
+ ## Embedded mode Flutter web applications can also render content into an arbitrary number of @@ -360,3 +409,46 @@ To learn more about other configuration options, check out [Customizing web app initialization][]. [Customizing web app initialization]: /platform-integration/web/initialization + +## Host element CSS requirements {: #host-element-css-requirements } + +When embedding Flutter directly into a DOM element (using `hostElement` +with single-view or `addView` in multi-view mode), Flutter sizes its +rendering canvas based on the computed dimensions of the host container. + +HTML container elements like `
` default to `height: auto` and +`position: static`. Without explicit CSS styling, an empty host element +has a computed height of `0px`. This causes Flutter's internal +`CustomElementDimensionsProvider` to compute the view height as zero, +which collapses the Flutter view and prevents content from rendering. + +### Mandatory CSS properties {: #mandatory-css-properties } + +To ensure Flutter renders correctly, apply the following CSS properties +to your host element: + +* **`width` and `height`**: + Set explicit or relative dimensions (for example, + `width: 100%; height: 500px;` or `height: 100%` within a sized parent). + The element must evaluate to a non-zero width and height. +* **`position: relative`** (or `position: absolute` / `position: fixed`): + Establishes a positioning context for the canvas and DOM overlay layers + that Flutter creates inside the container. +* **`overflow: hidden`**: + Prevents Flutter canvas and interaction elements from overflowing + the container boundaries or causing unexpected scrollbars on the host page. + +### Example CSS {: #example-css } + +```css title="styles.css" +#flutter_host { + width: 100%; + height: 600px; + position: relative; + overflow: hidden; +} +``` + +```html title="index.html" +
+``` From 5d4c65dbcd606b64ea3f96f0978f254dc78e30b3 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Tue, 18 Aug 2026 10:07:12 -0700 Subject: [PATCH 2/3] Incorporate the bot's feedback --- .../web/embedding-flutter-web.md | 31 ++++++++++++------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md b/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md index 97a390d5a4..45329527c4 100644 --- a/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md +++ b/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md @@ -73,23 +73,30 @@ based on your isolation, performance, and communication requirements: Isolation & sandboxing - Full browser sandboxing with separate JS global scope, DOM tree, and CSS styles. - Shares the same DOM tree, JavaScript context, and CSS styles with the host page. + Full browser sandboxing with separate JS global scope, DOM tree, + and CSS styles. + Shares the same DOM tree, JavaScript context, + and CSS styles with the host page. Memory & engine instances - Each iframe initializes its own Flutter engine, WebAssembly/JS runtime, and memory heap. - A single Flutter engine instance and memory heap can manage one or more views. + Each iframe initializes its own Flutter engine, + WebAssembly/JS runtime, and memory heap. + A single Flutter engine instance and memory heap can manage + one or more views (when using multiview). JavaScript interop - Communication requires asynchronous messaging (such as postMessage). - Direct synchronous communication using package:web and dart:js_interop. + Communication requires asynchronous messaging + (such as postMessage). + Direct synchronous communication using + package:web and dart:js_interop. Styling & layout Independent frame isolated from host page CSS. - Direct integration into host page CSS layout (such as flexbox and grid). + Direct integration into host page CSS layout + (such as flexbox and grid). State sharing @@ -98,8 +105,10 @@ based on your isolation, performance, and communication requirements: Best for - Third-party widgets, untrusted content, isolated micro-frontends, or simple drop-in embeds. - Embedded UI components in existing web apps, multi-view dashboards, and tight host-app integration. + Third-party widgets, untrusted content, isolated micro-frontends, + or simple drop-in embeds. + Embedded UI components in existing web apps, multi-view dashboards, + and tight host-app integration. @@ -418,8 +427,8 @@ rendering canvas based on the computed dimensions of the host container. HTML container elements like `
` default to `height: auto` and `position: static`. Without explicit CSS styling, an empty host element -has a computed height of `0px`. This causes Flutter's internal -`CustomElementDimensionsProvider` to compute the view height as zero, +has a computed height of `0px`. +This causes Flutter to compute the view height as zero, which collapses the Flutter view and prevents content from rendering. ### Mandatory CSS properties {: #mandatory-css-properties } From 9ef078cf43f5bbc66d105b87f6e1ec1ef15551ac Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Wed, 19 Aug 2026 14:01:36 -0700 Subject: [PATCH 3/3] Incorporating feedback --- .../content/platform-integration/web/embedding-flutter-web.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md b/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md index 45329527c4..bfb46fb9d3 100644 --- a/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md +++ b/sites/docs/src/content/platform-integration/web/embedding-flutter-web.md @@ -75,8 +75,7 @@ based on your isolation, performance, and communication requirements: Isolation & sandboxing Full browser sandboxing with separate JS global scope, DOM tree, and CSS styles. - Shares the same DOM tree, JavaScript context, - and CSS styles with the host page. + Shares the same DOM tree and JavaScript context. Memory & engine instances