BottomSheet#

See also

Material Design spec, Sheets: bottom

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

Two classes are available to you MDListBottomSheet and MDGridBottomSheet for standard bottom sheets dialogs:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/grid-list-bottomsheets.png

Usage MDListBottomSheet#

from kivy.lang import Builder

from kivymd.toast import toast
from kivymd.uix.bottomsheet import MDListBottomSheet
from kivymd.app import MDApp

KV = '''
MDScreen:

    MDTopAppBar:
        title: "Example BottomSheet"
        pos_hint: {"top": 1}
        elevation: 4

    MDRaisedButton:
        text: "Open list bottom sheet"
        on_release: app.show_example_list_bottom_sheet()
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class Example(MDApp):
    def build(self):
        return Builder.load_string(KV)

    def callback_for_menu_items(self, *args):
        toast(args[0])

    def show_example_list_bottom_sheet(self):
        bottom_sheet_menu = MDListBottomSheet()
        for i in range(1, 11):
            bottom_sheet_menu.add_item(
                f"Standart Item {i}",
                lambda x, y=i: self.callback_for_menu_items(
                    f"Standart Item {y}"
                ),
            )
        bottom_sheet_menu.open()


Example().run()

The add_item method of the MDListBottomSheet class takes the following arguments:

text - element text;

callback - function that will be called when clicking on an item;

There is also an optional argument icon, which will be used as an icon to the left of the item:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/icon-list-bottomsheets.png

Using the MDGridBottomSheet class is similar to using the MDListBottomSheet class:

from kivy.lang import Builder

from kivymd.toast import toast
from kivymd.uix.bottomsheet import MDGridBottomSheet
from kivymd.app import MDApp

KV = '''
MDScreen:

    MDTopAppBar:
        title: 'Example BottomSheet'
        pos_hint: {"top": 1}
        elevation: 4

    MDRaisedButton:
        text: "Open grid bottom sheet"
        on_release: app.show_example_grid_bottom_sheet()
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class Example(MDApp):
    def build(self):
        return Builder.load_string(KV)

    def callback_for_menu_items(self, *args):
        toast(args[0])

    def show_example_grid_bottom_sheet(self):
        bottom_sheet_menu = MDGridBottomSheet()
        data = {
            "Facebook": "facebook-box",
            "YouTube": "youtube",
            "Twitter": "twitter-box",
            "Da Cloud": "cloud-upload",
            "Camera": "camera",
        }
        for item in data.items():
            bottom_sheet_menu.add_item(
                item[0],
                lambda x, y=item[0]: self.callback_for_menu_items(y),
                icon_src=item[1],
            )
        bottom_sheet_menu.open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/grid-bottomsheet.png

You can use custom content for bottom sheet dialogs:

from kivy.lang import Builder
from kivy.factory import Factory

from kivymd.uix.bottomsheet import MDCustomBottomSheet
from kivymd.app import MDApp

KV = '''
<ItemForCustomBottomSheet@OneLineIconListItem>
    on_press: app.custom_sheet.dismiss()
    icon: ""

    IconLeftWidget:
        icon: root.icon


<ContentCustomSheet@BoxLayout>:
    orientation: "vertical"
    size_hint_y: None
    height: "400dp"

    MDTopAppBar:
        title: 'Custom bottom sheet:'

    ScrollView:

        MDGridLayout:
            cols: 1
            adaptive_height: True

            ItemForCustomBottomSheet:
                icon: "page-previous"
                text: "Preview"

            ItemForCustomBottomSheet:
                icon: "exit-to-app"
                text: "Exit"


MDScreen:

    MDTopAppBar:
        title: 'Example BottomSheet'
        pos_hint: {"top": 1}
        elevation: 4

    MDRaisedButton:
        text: "Open custom bottom sheet"
        on_release: app.show_example_custom_bottom_sheet()
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class Example(MDApp):
    custom_sheet = None

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

    def show_example_custom_bottom_sheet(self):
        self.custom_sheet = MDCustomBottomSheet(screen=Factory.ContentCustomSheet())
        self.custom_sheet.open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/custom-bottomsheet.png

Note

When you use the MDCustomBottomSheet class, you must specify the height of the user-defined content exactly, otherwise dp(100) heights will be used for your ContentCustomSheet class:

<ContentCustomSheet@BoxLayout>:
    orientation: "vertical"
    size_hint_y: None
    height: "400dp"

Note

The height of the bottom sheet dialog will never exceed half the height of the screen!

API - kivymd.uix.bottomsheet.bottomsheet#

class kivymd.uix.bottomsheet.bottomsheet.MDBottomSheet(**kwargs)#

ModalView class. See module documentation for more information.

Events:
on_pre_open:

Fired before the ModalView is opened. When this event is fired ModalView is not yet added to window.

on_open:

Fired when the ModalView is opened.

on_pre_dismiss:

Fired before the ModalView is closed.

on_dismiss:

Fired when the ModalView is closed. If the callback returns True, the dismiss will be canceled.

Changed in version 1.11.0: Added events on_pre_open and on_pre_dismiss.

Changed in version 2.0.0: Added property ‘overlay_color’.

Changed in version 2.1.0: Marked attach_to property as deprecated.

background#

Private attribute.

duration_opening#

The duration of the bottom sheet dialog 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.

radius#

The value of the rounding of the corners of the dialog.

radius is an NumericProperty and defaults to 25.

radius_from#

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

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

radius_from is an OptionProperty and defaults to None.

animation#

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

animation is an BooleanProperty and defaults to False.

bg_color#

Dialog background color in in (r, g, b, a) or string format.

bg_color is an ColorProperty and defaults to [].

value_transparent#

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

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

open(self, *args)#

Display the modal in the Window.

When the view is opened, it will be faded in with an animation. If you don’t want the animation, use:

view.open(animation=False)
add_widget(self, 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.

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)
dismiss(self, *args, **kwargs)#

Close the view if it is open.

If you really want to close the view, whatever the on_dismiss event returns, you can use the force keyword argument:

view = ModalView()
view.dismiss(force=True)

When the view is dismissed, it will be faded out before being removed from the parent. If you don’t want this animation, use:

view.dismiss(animation=False)
resize_content_layout(self, content, layout, interval=0)#
class kivymd.uix.bottomsheet.bottomsheet.MDCustomBottomSheet(**kwargs)#

ModalView class. See module documentation for more information.

Events:
on_pre_open:

Fired before the ModalView is opened. When this event is fired ModalView is not yet added to window.

on_open:

Fired when the ModalView is opened.

on_pre_dismiss:

Fired before the ModalView is closed.

on_dismiss:

Fired when the ModalView is closed. If the callback returns True, the dismiss will be canceled.

Changed in version 1.11.0: Added events on_pre_open and on_pre_dismiss.

Changed in version 2.0.0: Added property ‘overlay_color’.

Changed in version 2.1.0: Marked attach_to property as deprecated.

screen#

Custom content.

screen is an ObjectProperty and defaults to None.

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

ModalView class. See module documentation for more information.

Events:
on_pre_open:

Fired before the ModalView is opened. When this event is fired ModalView is not yet added to window.

on_open:

Fired when the ModalView is opened.

on_pre_dismiss:

Fired before the ModalView is closed.

on_dismiss:

Fired when the ModalView is closed. If the callback returns True, the dismiss will be canceled.

Changed in version 1.11.0: Added events on_pre_open and on_pre_dismiss.

Changed in version 2.0.0: Added property ‘overlay_color’.

Changed in version 2.1.0: Marked attach_to property as deprecated.

sheet_list#

sheet_list is an ObjectProperty and defaults to None.

add_item(self, text, callback, icon=None)#
Parameters:

  • text – element text;

  • callback – function that will be called when clicking on an item;

  • icon – which will be used as an icon to the left of the item;

class kivymd.uix.bottomsheet.bottomsheet.GridBottomSheetItem(**kwargs)#

This mixin class provides Button behavior. Please see the button behaviors module documentation for more information.

Events:
on_press

Fired when the button is pressed.

on_release

Fired when the button is released (i.e. the touch/click that pressed the button goes away).

source#

Icon path if you use a local image or icon name if you use icon names from a file kivymd/icon_definitions.py.

source is an StringProperty and defaults to ‘’.

caption#

Item text.

caption is an StringProperty and defaults to ‘’.

icon_size#

Icon size.

caption is an StringProperty and defaults to ’24sp’.

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

ModalView class. See module documentation for more information.

Events:
on_pre_open:

Fired before the ModalView is opened. When this event is fired ModalView is not yet added to window.

on_open:

Fired when the ModalView is opened.

on_pre_dismiss:

Fired before the ModalView is closed.

on_dismiss:

Fired when the ModalView is closed. If the callback returns True, the dismiss will be canceled.

Changed in version 1.11.0: Added events on_pre_open and on_pre_dismiss.

Changed in version 2.0.0: Added property ‘overlay_color’.

Changed in version 2.1.0: Marked attach_to property as deprecated.

add_item(self, text, callback, icon_src)#
Parameters:

  • text – element text;

  • callback – function that will be called when clicking on an item;

  • icon_src – icon item;