Repository navigation
Description
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:
- 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.
- 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.
- Eliminate the tofu box issue!
- Apple Emoji !
Here's a few examples of issues that we aim to close with WebParagraph:
- flutter web: use the device's default font instead of loading the large font filet from fonts.gstatic.com #163823
- Flutter 3.24 doesnt support Apple emojis #157918
- [Web] Don't show tofu boxes temporarily until suitable fonts are found and downloaded. #169455
- [web] Some Unicode fallbacks look bad #129329
- [web] Standardized way to preload emoji font using CanvasKit #78422
- [Web] [CanvasKit][Feature Request]: Load fonts as soon as detecting browser locale #77023
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-featuresenabled.
Important caveats & fallback behavior
--wasmis not supported yet:WebParagraphis currently wired up only in the default JavaScript (CanvasKit) web build (flutter build web/flutter run). In aflutter build web --wasmbuild,preferWebParagraph: trueis ignored unless you also setrenderer: 'canvaskit'inconfig(which falls back to the JavaScript + CanvasKit bundle).- Keep
canvasKitVariantat its default ('auto'or'chromium'): Do not setcanvasKitVariant: 'full'together withpreferWebParagraph: true(canvaskit/canvaskit.wasmdoes not include thecanvasKit.Bidimodule required byWebParagraph). - Automatic graceful fallback: On browsers where
window.TextClusteris unavailable (Chrome without the experimental flag, Safari, or Firefox), Flutter automatically falls back to standard CanvasKit text rendering (canvaskit/chromium/canvaskit.wasmorcanvaskit/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 ofcanvaskit/chromium/canvaskit.wasm(~5.46 MB).
Activity
[WebParagraph] More plumbing towards making it usable in Flutter apps (…
[WebParagraph] More plumbing towards making it usable in Flutter apps (…
[WebParagraph] More plumbing towards making it usable in Flutter apps (…
[WebParagraph] More plumbing towards making it usable in Flutter apps (…
[WebParagraph] Support for more styles, placeholders, decorations, etc (
Fixing zoom, dropping subpixel shift (#177460)
34 remaining items
[web] Refactor webparagraph painters to separate CK properly (flutter…
Fixing alignment issue (flutter#187518)
[web] Changes to WebParagraph configuration (flutter#187188)
[web] RenderParagraph needs paint after a DPR change (flutter#186968)
Implement font fallback (flutter#187520)
Fixing multiline GetBoxesForRange (flutter#188803)
[WebParagraph] More plumbing towards making it usable in Flutter apps…
[WebParagraph] Support for more styles, placeholders, decorations, et…
Fixing zoom, dropping subpixel shift (#177460)
WebParagrah: ellipsis (#178748)
[web] Run webparagraph tests in CI (#182092)
[-][web] ☂️ WebParagraph[/-][+][web] ☂️ TextMetrics (WebParagraph)[/+][-][web] ☂️ TextMetrics (WebParagraph)[/-][+][web] ☂️ WebParagraph (Enhanced TextMetrics API)[/+]feat(repo): prefer the native text of the browser in the web apps