Skip to content
Boring Doc
BreakingHigh impactOfficial migration guidesince 2.5.0landed 2.3.0-16.0.preweb

Using HTML slots to render platform views in the web

Framework · Official source

Flutter now renders all web platform views in a consistent location of the DOM, as direct children of `flt-glass-pane` (regardless of the rendering backend: `html` or `canvaskit`). Platform views are then _"slotted"_ into the correct position of the App's DOM with standard HTML features.

Original behavior

The Flutter framework frequently tweaks its render tree to optimize the paint operations that are ultimately made per frame. In the web, these render tree changes often result in DOM operations.

New behavior

A Flutter web app is now rendered inside a common shadow root in which slot elements represent platform views. The actual content of each platform view is rendered as a **sibling of said shadow root**.

Who is affected
Applications and packages relying on the previous behaviour or signature. Code that uses HtmlElementView, PlatformViewFactory.
Practical impact
Behaviour or API differences that can break builds or change runtime behaviour.
What action should I take?
Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.

Before and after (from the official guide)

dart+8−6
Before
1 ...
2  
3 <flt-glass-pane>
4− ...
5− <div id="platform-view">Contents</div> <!-- canvaskit -->
6− <!-- OR -->
7− <flt-platform-view>
8− #shadow-root
9− | <div id="platform-view">Contents</div> <!-- html -->
 
 
10 </flt-platform-view>
11 ...
12 </flt-glass-pane>
13  
14 ...
After
1 ...
2  
3 <flt-glass-pane>
4+ #shadow-root
5+ | ...
6+ | <flt-platform-view-slot>
7+ | <slot name="platform-view-1" />
8+ | </flt-platform-view-slot>
9+ | ...
10+ <flt-platform-view slot="platform-view-1">
11+ <div id="platform-view">Contents</div>
12 </flt-platform-view>
13 ...
14 </flt-glass-pane>
15  
16 ...
Raw before / after
...

<flt-glass-pane>
  ...
  <div id="platform-view">Contents</div> <!-- canvaskit -->
  <!-- OR -->
  <flt-platform-view>
    #shadow-root
    | <div id="platform-view">Contents</div> <!-- html -->
  </flt-platform-view>
  ...
</flt-glass-pane>

...
...

<flt-glass-pane>
  #shadow-root
  | ...
  | <flt-platform-view-slot>
  |   <slot name="platform-view-1" />
  | </flt-platform-view-slot>
  | ...
  <flt-platform-view slot="platform-view-1">
    <div id="platform-view">Contents</div>
  </flt-platform-view>
  ...
</flt-glass-pane>

...
Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)

Code

The engine may print a warning message to the console similar to:

Height of Platform View type: [$viewType] may not be set. Defaulting to `height: 100%`.
Set `style.height` to any appropriate value to stop this message.

or:

Width of Platform View type: [$viewType] may not be set. Defaulting to `width: 100%`.
Set `style.width` to any appropriate value to stop this message.

Previously, the content returned by [PlatformViewFactory functions][] was resized and positioned by the framework. Instead, Flutter now sizes and positions <flt-platform-view-slot>, which is the parent of the slot where the content is projected.

To stop the warning above, platform views need to set the style.width and style.height of their root element to any appropriate (non-null) value.

For example, to make the root html.Element fill all the available space allocated by the framework, set its style.width and style.height properties to '100%':

ui.platformViewRegistry.registerViewFactory(viewType, (int viewId) {
  final html.Element htmlElement = html.DivElement()
    // ..other props
    ..style.width = '100%'
    ..style.height = '100%';
  // ...
  return htmlElement;
});

If other techniques are used to lay out the platform view (like inset: 0) a value of auto for width and height is enough to stop the warning.

Read more about [CSS width][] and [CSS height][].

Tests

After this change, user's test code does not need to deeply inspect the contents of the shadow root of the App. All of the platform view contents will be placed as direct children of flt-glass-pane, wrapped in a flt-platform-view element.

Avoid looking inside the flt-glass-pane shadow root, it is considered a "private implementation detail", and its markup can change at any time, without notice.

(See Relevant PRs below for examples of the "migrations" described above).

Migration assistantAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.
Official migration guide·Verified classification (95%)

Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).

An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.

Source commit
b3045439b7c0
Source last updated
Oct 21, 2026
Last synchronized
Oct 21, 2026
Publication status
published
Publication history
  • Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI explanationAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.
Was this useful?