Skip to content

[web] ☂️ WebParagraph (Enhanced TextMetrics API) #172561

Open
10 of 15 issues completed
Open

Description

@mdebbar

What is WebParagraph?

It's a new implementation of Flutter's text layout system on the web (ParagraphBuilder, Paragraph, etc). This new implementation takes advantage of new browser APIs, namely Enhanced TextMetrics.

Why?

The browser already contains a full text layout system, but because it's not exposed to web apps, we had to bundle a lot of the same bits in each Flutter web app. By utilizing Enhanced TextMetrics, we can achieve the following:

  1. Reduce code size: Delete some parts of the text layout system that we don't need anymore: HarfBuzz, Font management, Freetype, Brotli decoder (was needed for Woff2), etc.
  2. Eliminate fallback fonts: Fallback fonts cost extra network bandwidth and add complexity. They were needed because we didn't have access to system/browser fonts.
  3. Eliminate the tofu box issue!
  4. Apple Emoji !

Here's a few examples of issues that we aim to close with WebParagraph:

How can I try it out?

An experimental preview of WebParagraph is available starting in Flutter 3.50 using the default CanvasKit web renderer and a Chromium-based browser with the Enhanced TextMetrics (ExtendedTextMetrics) experimental API enabled.

1. Enable the browser flag in Chrome / Chromium (132+)

Enhanced TextMetrics (window.TextCluster / TextMetrics.prototype.getTextClusters) is still behind an experimental Blink flag:

  • In Chrome UI: Open chrome://flags/#enable-experimental-web-platform-features, set it to Enabled, and relaunch Chrome.
  • Via CLI flag: Launch a fresh Chrome or Chromium instance with --enable-blink-features=ExtendedTextMetrics (or --enable-experimental-web-platform-features).

2. Enable preferWebParagraph in web/flutter_bootstrap.js

Create (or update) web/flutter_bootstrap.js in your Flutter project and pass preferWebParagraph: true in config:

{{flutter_js}}
{{flutter_build_config}}

_flutter.loader.load({
  config: {
    preferWebParagraph: true,
  },
});

3. Run or build your web app

  • Local development (flutter run):

    flutter run -d chrome --web-browser-flag=--enable-blink-features=ExtendedTextMetrics
  • Production build (flutter build web):

    flutter build web

    Then open the hosted app in Chrome with #enable-experimental-web-platform-features enabled.

Important caveats & fallback behavior

  • --wasm is not supported yet: WebParagraph is currently wired up only in the default JavaScript (CanvasKit) web build (flutter build web / flutter run). In a flutter build web --wasm build, preferWebParagraph: true is ignored unless you also set renderer: 'canvaskit' in config (which falls back to the JavaScript + CanvasKit bundle).
  • Keep canvasKitVariant at its default ('auto' or 'chromium'): Do not set canvasKitVariant: 'full' together with preferWebParagraph: true (canvaskit/canvaskit.wasm does not include the canvasKit.Bidi module required by WebParagraph).
  • Automatic graceful fallback: On browsers where window.TextCluster is unavailable (Chrome without the experimental flag, Safari, or Firefox), Flutter automatically falls back to standard CanvasKit text rendering (canvaskit/chromium/canvaskit.wasm or canvaskit/canvaskit.wasm) with zero runtime errors.
  • Verify it is active: In Chrome DevTools → Network, confirm that canvaskit/webparagraph/canvaskit.wasm (~3.75 MB) is loaded instead of canvaskit/chromium/canvaskit.wasm (~5.46 MB).

Activity

  1. added
    a: typographyText rendering, possibly libtxt
    platform-webWeb applications specifically
    P1High-priority issues at the top of the work list
    team-webOwned by Web platform team
    triaged-webTriaged by Web platform team
    on Jul 22, 2025
  2. 34 remaining items

  3. changed the title [-][web] ☂️ WebParagraph[/-] [+][web] ☂️ TextMetrics (WebParagraph)[/+] on Oct 14, 2026
  4. changed the title [-][web] ☂️ TextMetrics (WebParagraph)[/-] [+][web] ☂️ WebParagraph (Enhanced TextMetrics API)[/+] on Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

P1High-priority issues at the top of the work lista: typographyText rendering, possibly libtxtplatform-webWeb applications specificallyteam-webOwned by Web platform teamtriaged-webTriaged by Web platform team

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions