loadingBuilder property

A builder that specifies the widget to display to the user while an image is still loading.

If this is null, and the image is loaded incrementally (e.g. over a network), the user will receive no indication of the progress as the bytes of the image are loaded.

For more information on how to interpret the arguments that are passed to this builder, see the documentation on ImageLoadingBuilder.

Performance implications

If a loadingBuilder is specified for an image, the Image widget is likely to be rebuilt on every rendering pipeline frame until the image has loaded. This is useful for cases such as displaying a loading progress indicator, but for simpler cases such as displaying a placeholder widget that doesn't depend on the loading progress (e.g. static "loading" text), frameBuilder will likely work and not incur as much cost.

Chaining with frameBuilder

If a frameBuilder has also been specified for an image, the two builders will be chained together: the child argument to this builder will contain the result of the frameBuilder. For example, consider the following builders used in conjunction:

Image(
  image: _image,
  frameBuilder: (BuildContext context, Widget child, int? frame, bool? wasSynchronouslyLoaded) {
    return Padding(
      padding: const EdgeInsets.all(8.0),
      child: child,
    );
  },
  loadingBuilder: (BuildContext context, Widget child, ImageChunkEvent? loadingProgress) {
    return Center(child: child);
  },
)

In this example, the widget hierarchy will contain the following:

Center(
  child: Padding(
    padding: const EdgeInsets.all(8.0),
    child: image,
  ),
),

Run against a real-world image on a slow network, the previous example renders the following loading progress indicator while the image loads before rendering the completed image.