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..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 @@ -55,6 +55,63 @@ 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 and JavaScript context.
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 (when using multiview).
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 +417,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 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" +
+```