photo_view

To display multiple images that a user can swipe through, use PhotoViewGallery.builder. This approach uses PhotoViewGalleryPageOptions to configure each page in the gallery, allowing you to set the imageProvider, initialScale, and heroAttributes for each item.

import 'package:photo_view/photo_view.dart';
import 'package:photo_view/photo_view_gallery.dart';
// ...

@override
Widget build(BuildContext context) {
  return Container(
    child: PhotoViewGallery.builder(
      scrollPhysics: const BouncingScrollPhysics(),
      builder: (BuildContext context, int index) {
        return PhotoViewGalleryPageOptions(
          imageProvider: AssetImage(widget.galleryItems[index].image),
          initialScale: PhotoViewComputedScale.contained * 0.8,
          heroAttributes: PhotoViewHeroAttributes(tag: galleryItems[index].id),
        );
      },
      itemCount: galleryItems.length,
      loadingBuilder: (context, event) => Center(
        child: Container(
          width: 20.0,
          height: 20.0,
          child: CircularProgressIndicator(
            value: event == null
                ? 0
                : event.cumulativeBytesLoaded / event.expectedTotalBytes,
          ),
        ),
      ),
      backgroundDecoration: widget.backgroundDecoration,
      pageController: widget.pageController,
      onPageChanged: onPageChanged,
    )
  );
}

If you want to display something other than a standard Image widget (for example, a complex composition or a video player), you can use the PhotoViewCore.customChild constructor. This allows you to pass a customChild widget while still benefiting from the library's gesture handling, scaling, and rotation logic.

When using customChild, the imageProvider parameter is not required.

// Example of the customChild constructor pattern
const PhotoViewCore.customChild({
    Key? key,
    required this.customChild,
    required this.backgroundDecoration,
    this.heroAttributes,
    required this.enableRotation,
    this.onTapUp,
    this.onTapDown,
    this.onScaleEnd,
    this.gestureDetectorBehavior,
    required this.controller,
    required this.scaleBoundaries,
    required this.scaleStateCycle,
    required this.scaleStateController,
    required this.basePosition,
    required this.tightMode,
    required this.filterQuality,
    required this.disableGestures,
    required this.enablePanAlways,
    required this.strictScale,
  });

The PhotoViewCore widget is the internal engine of the library, but it defines the primary configuration surface for displaying images. When using the standard constructor, you must provide an imageProvider and several configuration parameters to manage scale, rotation, and gestures.

Key configuration properties include:

• imageProvider: The ImageProvider to be displayed.
• backgroundDecoration: A Decoration for the background (defaults to black).
• scaleBoundaries: Defines minScale, maxScale, and initialScale.
• controller: A PhotoViewControllerBase to manage the view state.
• scaleStateController: A PhotoViewScaleStateController to track the current scale state.
• enableRotation: Boolean to allow/disallow rotation gestures.
• strictScale: If true, scale updates are ignored if they exceed scaleBoundaries.
• enablePanAlways: If true, allows panning even when not scaled.
• filterQuality: Controls the FilterQuality of the image.

// Note: This is a conceptual representation of the PhotoViewCore constructor
// as it is an internal implementation detail, but it defines the required config surface.
const PhotoViewCore({
  required this.imageProvider,
  required this.backgroundDecoration,
  required this.semanticLabel,
  required this.gaplessPlayback,
  required this.heroAttributes,
  required this.enableRotation,
  required this.onTapUp,
  required this.onTapDown,
  required this.onScaleEnd,
  required this.gestureDetectorBehavior,
  required this.controller,
  required this.scaleBoundaries,
  required this.scaleStateCycle,
  required this.scaleStateController,
  required this.basePosition,
  required this.tightMode,
  required this.filterQuality,
  required this.disableGestures,
  required this.enablePanAlways,
  required this.strictScale,
});

The PhotoViewScaleStateController provides the following public interface for managing the scale state of a photo view: