Web renderers
When running and building apps for the web, you can choose between two different renderers. This page describes both renderers and how to choose the best one for your needs. The two renderers are:
- CanvasKit renderer
- This renderer is fully consistent with Flutter mobile and desktop, has faster performance with higher widget density, but adds about 1.5MB in download size. CanvasKit uses WebGL to render Skia paint commands.
- HTML renderer
- This renderer, which has a smaller download size than the CanvasKit renderer, uses a combination of HTML elements, CSS, Canvas elements, and SVG elements.
Command line options
#The --web-renderer
command line option takes one of three values: canvaskit
, html
, or auto
.
canvaskit
(soon to be default) - always use the CanvasKit rendererauto
(default) - automatically chooses which renderer to use. This option chooses the HTML renderer when the app is running in a mobile browser, and CanvasKit renderer when the app is running in a desktop browser.html
- always use the HTML renderer
This flag can be used with the run
or build
subcommands. For example:
flutter run -d chrome --web-renderer html
flutter build web --web-renderer canvaskit
This flag is ignored when a non-browser (mobile or desktop) device target is selected.
Runtime configuration
#To override the web renderer at runtime:
- Build the app with the
auto
option. - Set up custom web app initialization as described in Write a custom
flutter_bootstrap.js
. - Prepare a configuration object with the
renderer
property set to"canvaskit"
or"html"
. - Pass your prepared config object as the
config
property of a new object to the_flutter.loader.load
method that is provided by the earlier injected code.
<body>
<script>
{{flutter_js}}
{{flutter_build_config}}
// TODO: Replace this with your own code to determine which renderer to use.
const useHtml = true;
const config = {
renderer: useHtml ? "html" : "canvaskit",
};
_flutter.loader.load({
config: config,
});
</script>
</body>
The web renderer can't be changed after the Flutter engine startup process begins in main.dart.js
.
Choosing which option to use
#Choose the canvaskit
option (default) if you are prioritizing performance and pixel-perfect consistency on both desktop and mobile browsers.
Choose the html
option if you are optimizing download size over performance on both desktop and mobile browsers.
Choose the auto
option if you are optimizing for download size on mobile browsers and optimizing for performance on desktop browsers.
Examples
#Run in Chrome using the default renderer option (auto
):
flutter run -d chrome
Build your app in release mode, using the default (auto
) option:
flutter build web --release
Build your app in release mode, using just the CanvasKit renderer:
flutter build web --web-renderer canvaskit --release
Run your app in profile mode using the HTML renderer:
flutter run -d chrome --web-renderer html --profile
Unless stated otherwise, the documentation on this site reflects the latest stable version of Flutter. Page last updated on 2024-06-27. View source or report an issue.