BottomSheet

See also

Material Design spec, Sheets: bottom

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

Usage

MDScreen:

    [ Content screen ]

    MDBottomSheet:

The bottom sheet has two types:

• Standard

• Modal

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.

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

Standard bottom sheet example

Declarative KV styleDeclarative python style

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()

Modal

Like dialogs, modal bottom sheets appear in front of app content, disabling all other app functionality when they appear, and remaining on screen until confirmed, dismissed, or a required action has been taken.

Modal bottom sheet example

Declarative KV styleDeclarative python style

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()

            MDLabel:
                bold: True
                color: 1, 1, 1, 1
                text: "Tap to open the modal bottom sheet"

    MDBottomSheet:
        id: bottom_sheet
        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()

Tapping the scrim dismisses a modal bottom sheet.

Custom positioning

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

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:

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:

Add elements to MDBottomSheetDragHandleTitle class

MDBottomSheet:

    MDBottomSheetDragHandle:

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

        MDBottomSheetDragHandleButton:
            icon: "close"

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

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()

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"

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:

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.