BottomSheet#
See also Bottom sheets are surfaces containing supplementary content that are anchored to the bottom of the screen. The bottom sheet has two types: 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. 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. Tapping the scrim dismisses a modal bottom sheet. The optional drag handle provides an affordance for custom sheet height,
or for a quick toggle through preset heights. 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: To add custom content to the bottom sheet, use the
(A double tap on the map to open the bottom sheet)
Usage#
MDScreen:
[ Content screen ]
MDBottomSheet:
Standard#
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()
from kivy.clock import Clock
from kivy.metrics import dp
from kivymd.app import MDApp
from kivymd.uix.bottomsheet import MDBottomSheet
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.imagelist import MDSmartTile
from kivymd.uix.label import MDLabel
from kivymd.uix.screen import MDScreen
class Example(MDApp):
def build(self):
self.theme_cls.theme_style = "Dark"
return MDScreen(
MDBoxLayout(
MDSmartTile(
MDLabel(
id="tile_label",
text="Tap to open the bottom sheet",
bold=True,
color=(1, 1, 1, 1),
),
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",
),
id="box",
orientation="vertical",
padding="12dp",
pos_hint={"top": 1},
adaptive_height=True,
),
MDBottomSheet(
id="bottom_sheet",
size_hint_y=None,
type="standard",
bg_color="grey",
),
)
def open_bottom_sheet(self, *args):
bottom_sheet = self.root.ids.bottom_sheet
smart_tile = self.root.ids.box.ids.smart_tile
tile_label = smart_tile.ids.tile_label
bottom_sheet.open() if bottom_sheet.state == "close" else bottom_sheet.dismiss()
tile_label.text = (
"Tap to open the bottom sheet"
if bottom_sheet.state == "close"
else "Tap to close the bottom sheet"
)
def on_start(self):
def on_start(*args):
bottom_sheet = self.root.ids.bottom_sheet
smart_tile = self.root.ids.box.ids.smart_tile
bottom_sheet.default_opening_height = smart_tile.y - dp(12)
bottom_sheet.height = self.root.height - (
smart_tile.height + dp(24)
)
smart_tile.bind(on_release=lambda x: self.open_bottom_sheet())
Clock.schedule_once(on_start, 1.2)
Example().run()
Modal#
Modal 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()
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()
from kivy.clock import Clock
from kivy.metrics import dp
from kivymd.app import MDApp
from kivymd.uix.bottomsheet import MDBottomSheet
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.imagelist import MDSmartTile
from kivymd.uix.label import MDLabel
from kivymd.uix.screen import MDScreen
class Example(MDApp):
def build(self):
self.theme_cls.theme_style = "Dark"
return MDScreen(
MDBoxLayout(
MDSmartTile(
MDLabel(
id="tile_label",
text="Tap to open the modal bottom sheet",
bold=True,
color=(1, 1, 1, 1),
),
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",
),
id="box",
orientation="vertical",
padding="12dp",
pos_hint={"top": 1},
adaptive_height=True,
),
MDBottomSheet(
id="bottom_sheet",
size_hint_y=None,
bg_color="grey",
),
)
def open_bottom_sheet(self, *args):
bottom_sheet = self.root.ids.bottom_sheet
bottom_sheet.open()
def on_start(self):
def on_start(*args):
bottom_sheet = self.root.ids.bottom_sheet
smart_tile = self.root.ids.box.ids.smart_tile
bottom_sheet.default_opening_height = smart_tile.y - dp(12)
bottom_sheet.height = self.root.height - (
smart_tile.height + dp(24)
)
smart_tile.bind(on_release=lambda x: self.open_bottom_sheet())
Clock.schedule_once(on_start, 1.2)
Example().run()
Custom positioning#
MDBottomSheet:
MDBottomSheetDragHandle:
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#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#
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
classFor 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 anColorProperty
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.
- widget:
>>> 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
andCommonElevationBehavior
andTouchBehavior
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 aBooleanProperty
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 anOptionProperty
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 anBooleanProperty
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 anBooleanProperty
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 aStringProperty
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 aStringProperty
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 anNumericProperty
and defaults to dp(100).
- duration_opening#
The duration of the bottom sheet opening animation.
duration_opening
is anNumericProperty
and defaults to 0.15.
- duration_closing#
The duration of the bottom sheet dialog closing animation.
duration_closing
is anNumericProperty
and defaults to 0.15.
- animation#
Whether to use animation for opening and closing of the bottom sheet or not.
animation
is anBooleanProperty
and defaults to True.
- state#
Menu state. Available options are: ‘close’, ‘open’.
New in version 1.2.0.
state
is anOptionProperty
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 aColorProperty
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 anColorProperty
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 anOptionProperty
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 anColorProperty
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.
- touch:
- 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.
- widget:
>>> 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.