flet-m3-carousel

A Flet extension that wraps the Flutter m3_carousel package and exposes it as the M3Carousel layout control.

The carousel layout and animation are delegated to the upstream package. This wrapper does not reimplement them.

Platform support

Tested on Linux desktop. Other platforms are supported by the upstream package but were not tested here.

Installation

Install the Python package:

pip install flet-m3-carousel

The Flutter side is built into the Flet client. After changing Dart code, rebuild the client.

Quick start

import flet as ft
from flet_m3_carousel import M3Carousel, M3CarouselItem


def main(page: ft.Page):
    page.add(
        M3Carousel(
            height=320,
            layout="hero",
            axis="horizontal",
            hero_alignment="center",
            items=[
                M3CarouselItem(key="mountains", image="assets/mountains.jpg", title="Mountains"),
                M3CarouselItem(key="city", image="assets/city.jpg", title="City"),
                M3CarouselItem(key="ocean", image="assets/ocean.jpg", title="Ocean"),
            ],
            on_tap=lambda e: print(e.index, e.item_key),
        )
    )


ft.run(main)

Layouts

Events

• on_tap: fires when an item is tapped. Payload has index (zero based) and item_key.
• on_change: fires when the focal item changes after scrolling. Payload has index and item_key.

Demo

A runnable example is in examples/flet_m3_carousel_example. Build and run it with:

cd examples/flet_m3_carousel_example
flet build linux
flet run

Compatibility

This package follows Flet's extension model. Build the client after changing Dart code. Python-only changes do not require a rebuild.

Known limitations

• Item content is image-based. Arbitrary Flet controls are not supported as item content.
• Autoplay, infinite looping, custom physics, and custom spring curves are not exposed by the upstream package.
• Asset images must be declared in the app pubspec.yaml. A Python relative path is not a Flutter asset path.

License

MIT for this wrapper. The upstream package is also MIT licensed.