extended_image: Flutter image widget with network caching, crop editor and slide-out gesture

What extended_image adds over Flutter's built-in Image widget

Extended_image wraps Flutter's built-in Image widget and adds 6 capabilities the built-in component does not support. A feature comparison table in the README lists each: network image caching to local storage; compression display with 2 additional options (`compressionRatio` and `maxBytes`) that Flutter's Image lacks; automatic disposal of image resources where Flutter's Image requires manual management; a scaling mode; an editing mode for crop, rotate and flip; and a drag-to-dismiss effect for image page transitions.

Compression is the one area where both widgets overlap but extended_image offers more control. Flutter's Image provides `cacheHeight` and `cacheWidth`; extended_image adds `compressionRatio` and `maxBytes` on top of those. That is useful in list views loading many large remote images where trading display quality for memory is worth doing.

Automatic disposal of image resources addresses a common Flutter memory problem. Retaining image memory for off-screen items in a long scroll is a frequent source of memory pressure. Extended_image manages that lifecycle automatically, which is particularly relevant in photo gallery contexts where hundreds of items are loaded and unloaded as the user scrolls through the collection.

Adding extended_image to pubspec.yaml: null-safety and older SDK builds

2 installation paths exist. For null-safety projects on current Flutter SDK builds:

environment:
  sdk: '>=2.12.0 <3.0.0'
  flutter: '>=2.0'
dependencies:
  extended_image: ^4.0.0

For projects still targeting older Flutter builds:

environment:
  sdk: '>=2.6.0 <2.12.0'
  flutter: '>1.17.0 <=1.22.6'
dependencies:
  extended_image: ^3.0.0-non-null-safety

The Flutter API changed in a way that broke the older package series, so the 2 tracks are not interchangeable. Above the Flutter SDK boundary shown in the block above, the null-safety track applies; below it, the non-null-safety constraint is the compatible choice.

The null-safety block specifies `extended_image: ^4.0.0`, but GitHub tags for the repository end at v3.10.0 from 2023-05-16, which means the constraint in the pubspec block and the highest available tag do not agree.

For any new Flutter project on a current SDK, only the null-safety block is relevant. The non-null-safety track exists for projects that cannot migrate yet.

Network caching with ExtendedImage.network: cache is off in the constructor

`ExtendedImage.network` is the drop-in replacement for Flutter's network image call. A basic call with caching enabled:

ExtendedImage.network(
  url,
  width: ScreenUtil.instance.setWidth(400),
  height: ScreenUtil.instance.setWidth(400),
  fit: BoxFit.fill,
  cache: true,
  border: Border.all(color: Colors.red, width: 1.0),
  shape: boxShape,
  borderRadius: BorderRadius.all(Radius.circular(30.0)),
)

Passing `cache: true` is required, since the constructor sets `cache` to false and no image is written to local storage without that flag. `ExtendedNetworkImageProvider` retries 3 times by default, with `const Duration(milliseconds: 100)` between each attempt.

`headers` accepts HTTP headers for servers requiring authentication tokens or custom request fields. `timeLimit` sets a ceiling on total request duration; the constructor documentation does not list a default for it. `scale` sets the scale value in the `ImageInfo` object, with a default of 1.0 in the parameter table. A `CancellationToken` can be passed to cancel a pending request, and the constructor creates one internally when none is supplied.

Crop, rotate, flip and the ImageEditorController API

Extended_image's editing mode exposes 6 operations through `ImageEditorController`: `flip`, `rotate`, `cropAspectRatio`, `undo`, `redo` and `reset`. The table of contents also lists `history` and `update config` as sub-items of the editor section.

Flip, rotate and crop each take parameters through the controller rather than the widget constructor. A `cropAspectRatio` property controls the shape of the crop overlay, and a crop layer painter is listed as customisable. Replacing the default crop overlay with a custom painter matters for apps requiring a specific crop interface rather than the default visual.

For extracting the final crop result, 2 options are documented: a Dart library described as stable, and a native library described as faster. Neither is selected automatically. A project that prioritises portability stays on the Dart path. A project where extraction speed is a priority can use the native path at the cost of platform-specific build setup.

Undo and redo work against a history stack, and reset returns the image to its unedited state. The history sub-item in the table of contents confirms that multiple edit steps are tracked, not only a single step back. The `update config` sub-item signals that editor configuration can be changed after construction, though the specific config fields are not visible in the truncated README text. Photo View appears as a separate top-level section in the README table of contents, positioned between Editor and Slide Out Page; its full content is not in the truncated README, so it is listed as a distinct section from the Zoom Pan entry above it in the table of contents.

The slide-out page requires 4 explicit setup steps and a transparent background

Extended_image's drag-to-dismiss feature, called the slide-out page, is not a single widget property. Setting it up requires 4 explicit steps listed in the README: enable slide out page, include the page in `ExtendedImageSlidePage`, make the page background transparent, and push with a transparent page route.

A transparent background is a real layout constraint. Any non-transparent element in the page will clip the drag animation or produce visual artefacts as the image slides toward the edge. Content that should stay fixed during the gesture must be kept outside the `ExtendedImageSlidePage` wrapper or placed on a separate overlay layer, which is a layout change beyond what a single property toggle produces.

Using a transparent page route means the navigation call must change, not just the page layout. Every route that pushes to the image page needs updating, which is a wider change than adding a widget property. For existing apps adopting this feature, auditing navigation paths is part of the implementation work.

For projects built from scratch with this feature planned, the 4-step setup is manageable from the start. For apps integrating it later, the transparent background step is where visual regressions appear, since opaque containers in the page become visible only when the animation runs for the first time.

Flutter's built-in Image widget as the lighter alternative

Flutter's Image widget is the direct alternative when a project needs only basic image display. For network images where caching is the only requirement, the built-in widget paired with the 2 compression parameters it already supports (`cacheHeight` and `cacheWidth`) covers most list view use cases without an external package.

Extended_image is a superset of Flutter's Image interface, not a replacement for every context. Each of its 6 extensions adds setup work: caching requires the `cache: true` flag; zoom needs a mode configuration; the editor needs `ImageEditorController`; the slide-out page needs the 4-step process described in the previous section. Bringing the package into a project without using most of those extensions means carrying code that will not run.

Flutter's Image handles `cacheHeight` and `cacheWidth` natively. Projects needing only memory reduction from large images can set those 2 parameters without adding an external package at all. Extended_image adds `compressionRatio` and `maxBytes` on top, but confirming the need for that extra compression control before switching is worth doing.

The MIT licence text is in the LICENSE file at the repository root, and the last push was on 2026-07-12.

Further sections in the README and features the truncated text does not explain

Extended_image's README table of contents lists many top-level sections beyond Import, Cache Network and Editor: Load State, Zoom Pan, Photo View, Slide Out Page, Border BorderRadius Shape, Clear Save, Show Crop Image, Paint, Notch, MemoryUsage and Other APIs.

Several of these appear with no content in the truncated README. A MemoryUsage section is listed separately from the main feature set, which points to a dedicated monitoring API. Large image sets and high-resolution assets build memory pressure quickly; a separate section for memory usage confirms the package exposes tooling for it rather than leaving that entirely to the application layer.

`Paint` corresponds to a custom painting layer rendered over images, covering annotation, drawing tools and image markup features. `Clear Save` covers 2 operations: clearing the network image cache and saving a network image to device storage. `Notch` appears in the table of contents without description.

Border BorderRadius Shape is its own top-level section in the table of contents. The code block in the Cache Network section of the README already passes `border`, `shape` and `borderRadius` as parameters to `ExtendedImage.network` in the same call as `cache: true`, so those styling options work directly on the network image widget. Zoom Pan has 1 sub-item in the table of contents: double tap animation. Show Crop Image is listed between Clear Save and Paint as a top-level section with no sub-items in the truncated README.

Load State is a placeholder system showing loading and error widgets while the network image is in flight or has failed to arrive. Its presence as a separate section confirms it is configurable rather than a fixed fallback. For any feature beyond Import and Cache Network, the full README on GitHub or the web demo at fluttercandies.github.io/extended_image/ is the documentation source.

Editorial conclusion

extended_image is the right choice when a Flutter project needs at least 2 of its 6 built-in extensions together: network caching, zoom, an in-app crop/rotate/flip editor, load state placeholders, the slide-out page gesture, or custom paint over images. Using it for 1 extension only adds overhead a simpler package could avoid. Skip it when Flutter's built-in Image widget already covers your display needs. Before adopting, check pub.dev directly, since the GitHub tag list ends before the constraint the README's pubspec block specifies.

Frequently asked questions

Official sources

1. fluttercandies/extended_image on GitHub
2. License: MIT
3. Project website
4. README
5. Releases