Skip to content
Boring Doc
BreakingHigh impactOfficial migration guidesince 3.3.0landed 3.1.0-0.0.pre.976

Adding ImageProvider.loadBuffer

Framework · Official source

What changed?

* `ImageProvider` now has a method called `loadBuffer` that functions similarly to `load`, except that it decodes from an `ui.ImmutableBuffer`. * `ui.ImmutableBuffer` can now be created directly from an asset key. * The `AssetBundle` classes can now load an `ui.ImmutableBuffer`. * The `PaintingBinding` now has a method called `instantiateImageCodecFromBuffer`, which functions similarly to `instantiateImageCodec`. * `ImageProvider.load` is now deprecated, it will be removed in a future release. * `PaintingBinding.instantiateImageCodec` is now deprecated, it will be removed in a future release.

Original behavior

`ImageProvider.loadBuffer` is a new method that must be implemented in order to load images. This API allows asset-based image loading to be performed faster and with less memory impact on application.

New behavior

When loading asset images, previously the image provider API required multiple copies of the compressed data. First, when opening the asset the data was copied into the external heap and exposed to Dart as a typed data array. Then that typed data array was eventually converted into an `ui.ImmutableBuffer`, which internally copies the data into a second structure for decoding.

Will this affect my application?

Who is affected
Applications and packages relying on the previous behaviour or signature. Code that uses ImageProvider, AssetBundle, PaintingBinding and related APIs.
Practical impact
Behaviour or API differences that can break builds or change runtime behaviour.
What action should I take?
Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
APIs mentioned:ImageProviderAssetBundlePaintingBindingImageProvider.loadPaintingBinding.instantiateImageCodecImageProvider.loadBufferUint8ListImmutableBuffer

How do I migrate safely?

Before and after (from the official guide)

dart+6−5
Before
1 class MyImageProvider extends ImageProvider<MyImageProvider> {
2 @override
3− ImageStreamCompleter load(MyImageProvider key, DecoderCallback decode) {
4 return MultiFrameImageStreamCompleter(
5 codec: _loadData(key, decode),
6 );
7 }
8  
9− Future<ui.Codec> _loadData(MyImageProvider key, DecoderCallback decode) async {
10 final Uint8List bytes = await bytesFromSomeApi();
11− return decode(bytes);
 
12 }
13 }
14  
15 class MyDelegatingProvider extends ImageProvider<MyDelegatingProvider> {
16 MyDelegatingProvider(this.provider);
17  
18 final ImageProvider provider;
19  
20 @override
21− ImageStreamCompleter load(MyDelegatingProvider key, DecoderCallback decode) {
22− return provider.load(key, decode);
23 }
24 }
After
1 class MyImageProvider extends ImageProvider<MyImageProvider> {
2 @override
3+ ImageStreamCompleter loadBuffer(MyImageProvider key, DecoderBufferCallback decode) {
4 return MultiFrameImageStreamCompleter(
5 codec: _loadData(key, decode),
6 );
7 }
8  
9+ Future<ui.Codec> _loadData(MyImageProvider key, DecoderBufferCallback decode) async {
10 final Uint8List bytes = await bytesFromSomeApi();
11+ final ui.ImmutableBuffer buffer = await ui.ImmutableBuffer.fromUint8List(bytes);
12+ return decode(buffer);
13 }
14 }
15  
16 class MyDelegatingProvider extends ImageProvider<MyDelegatingProvider> {
17 MyDelegatingProvider(this.provider);
18  
19 final ImageProvider provider;
20  
21 @override
22+ ImageStreamCompleter loadBuffer(MyDelegatingProvider key, DecoderCallback decode) {
23+ return provider.loadBuffer(key, decode);
24 }
25 }
Raw before / after
class MyImageProvider extends ImageProvider<MyImageProvider> {
  @override
  ImageStreamCompleter load(MyImageProvider key, DecoderCallback decode) {
    return MultiFrameImageStreamCompleter(
        codec: _loadData(key, decode),
    );
  }

  Future<ui.Codec> _loadData(MyImageProvider key, DecoderCallback decode) async {
    final Uint8List bytes = await bytesFromSomeApi();
    return decode(bytes);
  }
}

class MyDelegatingProvider extends ImageProvider<MyDelegatingProvider> {
  MyDelegatingProvider(this.provider);

  final ImageProvider provider;

  @override
  ImageStreamCompleter load(MyDelegatingProvider key, DecoderCallback decode) {
    return provider.load(key, decode);
  }
}
class MyImageProvider extends ImageProvider<MyImageProvider> {
  @override
  ImageStreamCompleter loadBuffer(MyImageProvider key, DecoderBufferCallback decode) {
    return MultiFrameImageStreamCompleter(
        codec: _loadData(key, decode),
    );
  }

  Future<ui.Codec> _loadData(MyImageProvider key, DecoderBufferCallback decode) async {
    final Uint8List bytes = await bytesFromSomeApi();
    final ui.ImmutableBuffer buffer = await ui.ImmutableBuffer.fromUint8List(bytes);
    return decode(buffer);
  }
}

class MyDelegatingProvider extends ImageProvider<MyDelegatingProvider> {
  MyDelegatingProvider(this.provider);

  final ImageProvider provider;

  @override
  ImageStreamCompleter loadBuffer(MyDelegatingProvider key, DecoderCallback decode) {
    return provider.loadBuffer(key, decode);
  }
}
Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)

Classes that subclass ImageProvider must implement the loadBuffer method for loading assets. Classes that delegate to or call the methods of an ImageProvider directly must use loadBuffer instead of load.

Code before migration:

class MyImageProvider extends ImageProvider&#x3C;MyImageProvider> {
  @override
  ImageStreamCompleter load(MyImageProvider key, DecoderCallback decode) {
    return MultiFrameImageStreamCompleter(
        codec: _loadData(key, decode),
    );
  }

  Future&#x3C;ui.Codec> _loadData(MyImageProvider key, DecoderCallback decode) async {
    final Uint8List bytes = await bytesFromSomeApi();
    return decode(bytes);
  }
}

class MyDelegatingProvider extends ImageProvider&#x3C;MyDelegatingProvider> {
  MyDelegatingProvider(this.provider);

  final ImageProvider provider;

  @override
  ImageStreamCompleter load(MyDelegatingProvider key, DecoderCallback decode) {
    return provider.load(key, decode);
  }
}

Code after migration:

class MyImageProvider extends ImageProvider&#x3C;MyImageProvider> {
  @override
  ImageStreamCompleter loadBuffer(MyImageProvider key, DecoderBufferCallback decode) {
    return MultiFrameImageStreamCompleter(
        codec: _loadData(key, decode),
    );
  }

  Future&#x3C;ui.Codec> _loadData(MyImageProvider key, DecoderBufferCallback decode) async {
    final Uint8List bytes = await bytesFromSomeApi();
    final ui.ImmutableBuffer buffer = await ui.ImmutableBuffer.fromUint8List(bytes);
    return decode(buffer);
  }
}

class MyDelegatingProvider extends ImageProvider&#x3C;MyDelegatingProvider> {
  MyDelegatingProvider(this.provider);

  final ImageProvider provider;

  @override
  ImageStreamCompleter loadBuffer(MyDelegatingProvider key, DecoderCallback decode) {
    return provider.loadBuffer(key, decode);
  }
}

In both cases you might choose to keep the previous implementation of ImageProvider.load to give users of your code time to migrate as well.

Migration assistantAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.

Evidence & verification

Official migration guide·Verified classification (95%)

Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).

An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.

Source commit
b3045439b7c0
Source last updated
Oct 21, 2026
Last synchronized
Oct 21, 2026
Publication status
published
Publication history
  • Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI explanationAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.
Was this useful?