Bottom Sheet

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 = '''
Screen:

    MDToolbar:
        title: "Example BottomSheet"
        pos_hint: {"top": 1}
        elevation: 10

    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 = '''
Screen:

    MDToolbar:
        title: 'Example BottomSheet'
        pos_hint: {"top": 1}
        elevation: 10

    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"

    MDToolbar:
        title: 'Custom bottom sheet:'

    ScrollView:

        MDGridLayout:
            cols: 1
            adaptive_height: True

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

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


Screen:

    MDToolbar:
        title: 'Example BottomSheet'
        pos_hint: {"top": 1}
        elevation: 10

    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

class kivymd.uix.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’.

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 rgba format.

bg_color is an ColorProperty and defaults to [].

value_transparent

Background transparency value when opening a dialog.

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

open(self, *args)

Show the view window from the attach_to widget. If set, it will attach to the nearest window. If the widget is not attached to any window, the view will attach to the global 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 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 animation, use:

view.dismiss(animation=False)
resize_content_layout(self, content, layout, interval=0)
class kivymd.uix.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’.

screen

Custom content.

screen is an ObjectProperty and defaults to None.

class kivymd.uix.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’.

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

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;