Carousel

Added in version 2.0.0.

See also

Material Design spec, Carousel

Carousels show a collection of items that can be scrolled on and off the screen.

• Contain visual items like images or video, along with optional label text

• Six layouts: Multi-browse, uncontained, uncontained multi-aspect ratio, hero, center-aligned hero and full-screen

• Layouts can be start-aligned or center-aligned

• Item visuals have a parallax effect when scrolled

• Items change size as they move through the carousel

Usage

Imperative python styleDeclarative python style

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.carousel import MDCarouselItem
from kivymd.uix.fitimage import FitImage


KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDCarousel:
        id: carousel
        layouts: "multi-browse"
'''


class ExampleApp(MDApp):
    def on_start(self):
        for i in range(1, 20):
            carousel_item = MDCarouselItem()
            image = FitImage(
                source=f"https://picsum.photos/800/600?random={i}",
                radius=[dp(28)],
            )

            carousel_item.add_widget(image)
            self.root.ids.carousel.add_widget(carousel_item)

    def build(self):
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)


if __name__ == "__main__":
    ExampleApp().run()

Anatomy

API - kivymd.uix.carousel.carousel

class kivymd.uix.carousel.carousel.MDCarouselItem(*args, **kwargs)

Implements a item for MDCarousel class.

For more information, see in the MDCard class documentation.

Events:

on_slide_left

Fired when user slides/swipes to the left.

on_slide_right

Fired when user slides/swipes to the right.

on_slide_up

Fired when user slides/swipes up.

on_slide_down

Fired when user slides/swipes down.

on_index

Fired when the active slide index changes.

full_screen_radius

Corner radius used during scrolling for items in full-screen layout modes.

full_screen_radius is a NumericProperty and defaults to dp(16).

radius

Item radius by default.

radius is an VariableListProperty and defaults to [dp(28), dp(28), dp(28), dp(28)].

add_widget(widget, index=0, canvas=None)

Add a new widget as a child of this widget.

Parameters:

widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

Added in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

Added in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

class kivymd.uix.carousel.carousel.MDCarousel(**kwargs)

Implements a custom Material Design 3 carousel.

For more information, see in the MDWidget class documentation.

padding

Padding of the carousel view in the format [left, top, right, bottom].

padding is an ListProperty and defaults to [dp(16), dp(16), dp(16), dp(16)].

spacing

Distance between items in the carousel.

spacing is an NumericProperty and defaults to dp(12).

shrink_extent

Size of the collapsed or shrinked extent for trailing items.

shrink_extent is an NumericProperty and defaults to dp(56).

item_snapping

If True, enables automatic snapping of items to the closest slot upon touch release.

item_snapping is an BooleanProperty and defaults to True.

scroll_offset

Current scroll offset value of the carousel.

scroll_offset is an NumericProperty and defaults to 0.

layouts

Layout type of the carousel view.

Available options are: - "multi-browse": Standard layout displaying multiple items of varying sizes. - "uncontained": Items maintain a fixed width and overflow beyond the carousel edge. - "hero": Highlights a single large hero item aligned to the start. - "center-aligned": Displays a centered hero item flanked by smaller preview items. - "full-screen-horizontal": Items occupy the full width and height of the carousel, scrolling horizontally. - "full-screen-vertical": Items occupy the full width and height of the carousel, scrolling vertically.

layouts is an OptionProperty and defaults to "multi-browse".

Multi-browse

MDCarousel:
    layouts: "multi-browse"

Uncontained

MDCarousel:
    layouts: "uncontained"

Hero

MDCarousel:
    layouts: "hero"

Center-aligned

MDCarousel:
    layouts: "center-aligned"

Full-screen-vertical

MDCarousel:
    layouts: "full-screen-vertical"

Full-screen-horizontal

MDCarousel:
    layouts: "full-screen-horizontal"

uncontained_item_width

Width of individual items when using the "uncontained" layout mode.

uncontained_item_width is an NumericProperty and defaults to dp(280).

index

Index of the currently active item.

index is an NumericProperty and defaults to 0.

add_widget(widget, index=0, canvas=None)

Add a new widget as a child of this widget.

Parameters:

widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

Added in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

Added in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

on_touch_down(touch)

Receive a touch down event.

Parameters:

touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_touch_move(touch)

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_up(touch)

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_index(instance, value)

Fired when the active slide index changes.

on_slide_left()

Fired when user slides/swipes to the left.

on_slide_right()

Fired when user slides/swipes to the right.

on_slide_up()

Fired when user slides/swipes up.

on_slide_down()

Fired when user slides/swipes down.