flet-image-viewer

flet-image-viewer is a Flet extension for displaying zoomable images and swipeable image galleries in Flet applications.

The package provides FletImageViewer for a single image and FletMultiViewer for a swipeable gallery. Both controls support pinch-to-zoom, configurable image fitting, overlays, and long-press or double-tap events.

Demo

Want to see it in action? Watch the sample demo video.

Installation

Install the published package from PyPI:

pip install flet-image-viewer

Or add it to your application's pyproject.toml:

[project]
dependencies = [
    "flet>=0.86.5",
    "flet-image-viewer",
]

To install the latest version directly from GitHub instead, use:

[project]
dependencies = [
    "flet>=0.86.5",
    "flet-image-viewer @ git+https://github.com/zaim-tech/flet-image-viewer.git",
]

Usage

import flet as ft

from flet_image_viewer import FletImageViewer


def main(page: ft.Page):
    page.title = "Image viewer example"
    page.add(
        FletImageViewer(
            src="https://picsum.photos/900/600",
            show_close_button=True,
            BoxFit=ft.BoxFit.CONTAIN,
            min_scale=1.0,
            max_scale=4.0,
            expand=True,
        )
    )


ft.run(main)

The src property accepts an image URL or a local file path. For example:

base = os.path.dirname(os.path.abspath(__file__))
image = os.path.join(base, "assets/photo.jpg")
FletImageViewer(src=image)

Swipeable gallery

Use FletMultiViewer to display multiple images. The index property selects the image shown first, starting at 0.

import flet as ft

from flet_image_viewer import FletMultiViewer


def main(page: ft.Page):
    page.add(
        FletMultiViewer(
            src=[
                "https://picsum.photos/id/10/900/600",
                "https://picsum.photos/id/20/900/600",
                "https://picsum.photos/id/30/900/600",
            ],
            viewer_id="photo-gallery",
            index=0,
            BoxFit=ft.BoxFit.CONTAIN,
            overlay=ft.Container(
                content=ft.Text("Swipe to view more"),
                bgcolor=ft.Colors.with_opacity(0.75, ft.Colors.BLACK),
                padding=10,
            ),
            on_long_press=lambda event: print("Image long-pressed"),
            on_double_tap=lambda event: print("Image double-tapped"),
            expand=True,
        )
    )


ft.run(main)

Control properties

Events

Register handlers directly on either viewer:

def handle_double_tap(event: ft.ControlEvent):
    print("Viewer double-tapped")


viewer = FletImageViewer(
    src="https://picsum.photos/900/600",
    on_double_tap=handle_double_tap,
)

Platform support

The extension supports all Flet platforms except Web:

Build and run

For desktop development, build the client once and then use flet run:

flet build windows
flet run

Rebuild the client when the extension's Dart code changes. Python-only changes can be picked up with the normal Flet development workflow after the extension has been built.

Build the example

The example application is in examples/flet_image_viewer_example/:

cd examples/flet_image_viewer_example
flet build windows
flet run

Replace windows with another supported desktop or mobile target.

Documentation

See the complete API documentation for the generated control reference.

Development

The project follows Flet's extension structure:

src/flet_image_viewer/               Python controls
src/flutter/flet_image_viewer/       Native Flutter extension
examples/flet_image_viewer_example/  Sample Flet application
docs/                                API documentation

License

See LICENSE.

Made with ❤️ by Zaim Sheali