Contents

Web renderers

Contents

Command line options
Runtime configuration
Choosing which option to use
Examples

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:

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.
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.

The --web-renderer command line option takes one of three values, auto, html, or canvaskit.

auto (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
canvaskit - always use the CanvasKit 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.

To override the web renderer at runtime:

Build the app with the auto option.
Prepare a configuration object with the renderer property set to "canvaskit" or "html".
Pass that object to the engineInitializer.initializeEngine(configuration); method in the Flutter Web app initialization script.

html<body>
  <script>
    let useHtml = true;

    window.addEventListener('load', function(ev) {
    _flutter.loader.loadEntrypoint({
      serviceWorker: {
        serviceWorkerVersion: serviceWorkerVersion,
      },
      onEntrypointLoaded: function(engineInitializer) {
        let config = {
          renderer: useHtml ? "html" : "canvaskit",
        };
        engineInitializer.initializeEngine(config).then(function(appRunner) {
          appRunner.runApp();
        });
      }
    });
  });
  </script>
</body>

The web renderer can't be changed after the Flutter engine startup process begins in main.dart.js.

Choose the auto option (default) if you are optimizing for download size on mobile browsers and optimizing for performance on desktop browsers.

Choose the html option if you are optimizing download size over performance on both desktop and mobile browsers.

Choose the canvaskit option if you are prioritizing performance and pixel-perfect consistency on both desktop and mobile browsers.

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

Command line options

Runtime configuration

Choosing which option to use

Examples