BottomSheet#

Bottom sheets are surfaces containing supplementary content that are anchored to the bottom of the screen.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet.png

Usage#

MDScreen:

    [ Content screen ]

    MDBottomSheet:

The bottom sheet has two types:

Standard#

Standard bottom sheets co-exist with the screen’s main UI region and allow for simultaneously viewing and interacting with both regions, especially when the main UI region is frequently scrolled or panned.

Use a standard bottom sheet to display content that complements the screen’s primary content, such as an audio player in a music app.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-standard.png

Standard bottom sheets are elevated above the main UI region so their visibility is not affected by panning or scrolling.

Standard bottom sheet example#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDBoxLayout:
        orientation: "vertical"
        padding: "12dp"
        adaptive_height: True
        pos_hint: {"top": 1}

        MDSmartTile:
            id: smart_tile
            source: "https://picsum.photos/id/70/3011/2000"
            radius: 16
            box_radius: [0, 0, 16, 16]
            size_hint_y: None
            height: "240dp"
            on_release:
                bottom_sheet.open() \
                if bottom_sheet.state == "close" else \
                bottom_sheet.dismiss()

            MDLabel:
                bold: True
                color: 1, 1, 1, 1
                text:
                    "Tap to open the bottom sheet" \
                    if bottom_sheet.state == "close" else \
                    "Tap to close the bottom sheet"

    MDBottomSheet:
        id: bottom_sheet
        type: "standard"
        bg_color: "grey"
        default_opening_height: smart_tile.y - dp(12)
        size_hint_y: None
        height: root.height - (smart_tile.height + dp(24))
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-standard-example.gif

Custom positioning#

The optional drag handle provides an affordance for custom sheet height, or for a quick toggle through preset heights.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-drag-handle.png
MDBottomSheet:

    MDBottomSheetDragHandle:

By default, when you drag and then release the drag handle, the bottom sheet will be closed or expand to the full screen, depending on whether you released the drag handle closer to the top or to the bottom of the screen:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-drag-handle.gif

In order to manually adjust the height of the bottom sheet with the drag handle, set the auto_positioning parameter to False:

MDBottomSheet:
    auto_positioning: False

    MDBottomSheetDragHandle:
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-drag-handle-auto-positioning.gif

Add elements to MDBottomSheetDragHandleTitle class#

MDBottomSheet:

    MDBottomSheetDragHandle:

        MDBottomSheetDragHandleTitle:
            text: "MDBottomSheet"
            adaptive_height: True
            font_style: "H6"
            pos_hint: {"center_y": .5}

        MDBottomSheetDragHandleButton:
            icon: "close"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-drag-handle-elements.png

Add custom content to MDBottomSheet class#

To add custom content to the bottom sheet, use the MDBottomSheetContent class:

MDBottomSheet:
    bg_color: "darkgrey"
    type: "standard"
    max_opening_height: self.height
    default_opening_height: self.max_opening_height
    adaptive_height: True

    MDBottomSheetDragHandle:
        drag_handle_color: "grey"

    MDBottomSheetContent:
        padding: "16dp"

        MDLabel:
            text: "Content"
            halign: "center"
            font_style: "H5"
            adaptive_height: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-content.png

A practical example with standard bottom sheet#

(A double tap on the map to open the bottom sheet)

from kivy.lang import Builder
from kivy.properties import StringProperty, ObjectProperty, BooleanProperty
from kivy_garden.mapview import MapView

from kivymd.app import MDApp
from kivymd.uix.behaviors import TouchBehavior
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.utils import asynckivy

KV = '''
#:import MapSource kivy_garden.mapview.MapSource
#:import asynckivy kivymd.utils.asynckivy


<TypeMapElement>
    orientation: "vertical"
    adaptive_height: True
    spacing: "8dp"

    MDIconButton:
        id: icon
        icon: root.icon
        md_bg_color: "#EDF1F9" if not root.selected else app.theme_cls.primary_color
        pos_hint: {"center_x": .5}
        theme_icon_color: "Custom"
        icon_color: "white" if root.selected else "black"
        on_release: app.set_active_element(root, root.title.lower())

    MDLabel:
        font_size: "14sp"
        text: root.title
        pos_hint: {"center_x": .5}
        halign: "center"
        adaptive_height: True


MDScreen:

    CustomMapView:
        bottom_sheet: bottom_sheet
        map_source: MapSource(url=app.map_sources[app.current_map])
        lat: 46.5124
        lon: 47.9812
        zoom: 12

    MDBottomSheet:
        id: bottom_sheet
        elevation: 2
        shadow_softness: 6
        bg_color: "white"
        type: "standard"
        max_opening_height: self.height
        default_opening_height: self.max_opening_height
        adaptive_height: True
        on_open: asynckivy.start(app.generate_content())

        MDBottomSheetDragHandle:
            drag_handle_color: "grey"

            MDBottomSheetDragHandleTitle:
                text: "Select type map"
                adaptive_height: True
                bold: True
                pos_hint: {"center_y": .5}

            MDBottomSheetDragHandleButton:
                icon: "close"
                _no_ripple_effect: True
                on_release: bottom_sheet.dismiss()

        MDBottomSheetContent:
            id: content_container
            padding: 0, 0, 0, "16dp"
'''


class TypeMapElement(MDBoxLayout):
    selected = BooleanProperty(False)
    icon = StringProperty()
    title = StringProperty()


class CustomMapView(MapView, TouchBehavior):
    bottom_sheet = ObjectProperty()

    def on_double_tap(self, touch, *args):
        if self.bottom_sheet:
            self.bottom_sheet.open()


class Example(MDApp):
    map_sources = {
        "street": "https://mt1.google.com/vt/lyrs=m&x={x}&y={y}&z={z}",
        "sputnik": "https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}",
        "hybrid": "https://mt1.google.com/vt/lyrs=y&x={x}&y={y}&z={z}",
    }
    current_map = StringProperty("street")

    async def generate_content(self):
        icons = {
            "street": "google-street-view",
            "sputnik": "space-station",
            "hybrid": "map-legend",
        }
        if not self.root.ids.content_container.children:
            for i, title in enumerate(self.map_sources.keys()):
                await asynckivy.sleep(0)
                self.root.ids.content_container.add_widget(
                    TypeMapElement(
                        title=title.capitalize(),
                        icon=icons[title],
                        selected=not i,
                    )
                )

    def set_active_element(self, instance, type_map):
        for element in self.root.ids.content_container.children:
            if instance == element:
                element.selected = True
                self.current_map = type_map
            else:
                element.selected = False

    def build(self):
        return Builder.load_string(KV)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-sheet-real-example.gif

API - kivymd.uix.bottomsheet.bottomsheet#

class kivymd.uix.bottomsheet.bottomsheet.MDBottomSheetContent(*args, **kwargs)#

Implements a container for custom content for the MDBottomSheet class

For more information, see in the MDBoxLayout class documentation.

New in version 1.2.0.

class kivymd.uix.bottomsheet.bottomsheet.MDBottomSheetDragHandleButton(*args, **kwargs)#

Implements a close button (or other functionality) for the MDBottomSheetDragHandle container.

For more information, see in the MDIconButton class documentation.

New in version 1.2.0.

class kivymd.uix.bottomsheet.bottomsheet.MDBottomSheetDragHandleTitle(*args, **kwargs)#

Implements a header for the MDBottomSheetDragHandle container.

For more information, see in the MDLabel class documentation.

New in version 1.2.0.

class kivymd.uix.bottomsheet.bottomsheet.MDBottomSheetDragHandle(*args, **kwargs)#

Implements a container that can place the header of the bottom sheet and the close button. Also implements the event of dragging the bottom sheet on the parent screen.

For more information, see in the MDBoxLayout class documentation.

New in version 1.2.0.

drag_handle_color#

Color of drag handle element in (r, g, b, a) or string format.

MDBottomSheet:

    MDBottomSheetDragHandle:
        drag_handle_color: "white"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-sheet-drag-handle-color.png

drag_handle_color is an ColorProperty and defaults to None.

add_widget(self, widget, *args, **kwargs)#

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.

New 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.

New 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.bottomsheet.bottomsheet.MDBottomSheet(*args, **kwargs)#

Bottom sheet class.

For more information, see in the MDBoxLayout and CommonElevationBehavior and TouchBehavior classes documentation.

Events:
on_open

Event when opening the bottom sheet.

on_close

Event when closing the bottom sheet.

on_progress

Bottom sheet opening/closing progress event.

auto_dismiss#

This property determines if the view is automatically dismissed when the user clicks outside it.

New in version 1.2.0.

auto_dismiss is a BooleanProperty and defaults to True.

type#

Type sheet. There are two types of bottom sheets: standard and modal. Available options are: ‘modal’, ‘standard’.

New in version 1.2.0.

type is an OptionProperty and defaults to ‘modal.

auto_positioning#

Close or expand the bottom menu automatically when you release the drag handle.

New in version 1.2.0.

auto_positioning is an BooleanProperty and defaults to True.

max_opening_height#

The maximum height a that the bottom sheet can be opened using the drag handle.

New in version 1.2.0.

MDBottomSheet:
    max_opening_height: "300dp"

    MDBottomSheetDragHandle:
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-max-opening-height.gif

max_opening_height is an BooleanProperty and defaults to None.

opening_transition#

The name of the animation transition type to use when animating to the state ‘open’.

New in version 1.2.0.

opening_transition is a StringProperty and defaults to ‘out_cubic’.

closing_transition#

The name of the animation transition type to use when animating to the state ‘close’.

New in version 1.2.0.

closing_transition is a StringProperty and defaults to ‘out_sine’.

default_opening_height#

Default opening height of the bottom sheet.

New in version 1.2.0.

default_opening_height is an NumericProperty and defaults to dp(100).

duration_opening#

The duration of the bottom sheet opening animation.

duration_opening is an NumericProperty and defaults to 0.15.

duration_closing#

The duration of the bottom sheet dialog closing animation.

duration_closing is an NumericProperty and defaults to 0.15.

animation#

Whether to use animation for opening and closing of the bottom sheet or not.

animation is an BooleanProperty and defaults to True.

state#

Menu state. Available options are: ‘close’, ‘open’.

New in version 1.2.0.

state is an OptionProperty and defaults to ‘close’.

scrim_layer_color#

Color for scrim in (r, g, b, a) or string format.

New in version 1.2.0.

scrim_layer_color is a ColorProperty and defaults to [0, 0, 0, 1].

bg_color#

Background color of bottom sheet in (r, g, b, a) or string format.

bg_color is an ColorProperty and defaults to None.

radius_from#

Sets which corners to cut from the dialog. Available options are: “top_left”, “top_right”, “top”, “bottom_right”, “bottom_left”, “bottom”.

Deprecated since version 1.2.0: Use radius instead.

radius_from is an OptionProperty and defaults to None.

value_transparent#

Background color in (r, g, b, a) or string format transparency value when opening a dialog.

Deprecated since version 1.2.0.

value_transparent is an ColorProperty and defaults to [0, 0, 0, 0.8].

on_progress(self, *args)#

Bottom sheet opening/closing progress event.

on_open(self, *args)#

Event when opening the bottom sheet.

on_close(self, *args)#

Event when closing the bottom sheet.

on_long_touch(self, touch, *args)#

Called when the widget is pressed for a long time.

on_touch_down(self, 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_up(self, touch)#

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

See on_touch_down() for more information.

on_touch_move(self, touch)#

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

See on_touch_down() for more information.

on_type(self, *args)#
add_scrim_layer(self, *args)#

Adds a scrim layer to the parent widget on which the bottom sheet will be displayed.

check_max_opening_height(self, *args)#
check_parent(self, *args)#

Checks the type of parent widget to which the bottom sheet will be added.

dismiss(self, *args)#

Dismiss of bottom sheet.

expand(self)#

Expand of bottom sheet.

open(self, *args)#

Opening of bottom sheet.

clear_content(self)#

Removes custom content from the bottom sheet.

add_widget(self, widget, *args, **kwargs)#

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.

New 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.

New 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.bottomsheet.bottomsheet.MDCustomBottomSheet(*args, **kwargs)#

Deprecated since version 1.2.0.

Use MDBottomSheet class instead.

class kivymd.uix.bottomsheet.bottomsheet.MDListBottomSheet(*args, **kwargs)#

Deprecated since version 1.2.0.

Use MDBottomSheet class instead.

class kivymd.uix.bottomsheet.bottomsheet.MDGridBottomSheet(*args, **kwargs)#

Deprecated since version 1.2.0.

Use MDBottomSheet class instead.