material-components-android
Bottom sheets
Bottom sheets are surfaces containing supplementary content that are anchored to the bottom of the screen. There are two variants of bottom sheets.
- Standard
- Modal
Design & API documentation
Using bottom sheets
Before you can use Material bottom sheets, you need to add a dependency to the Material Components for Android library. For more information, see the Getting started page.
Anatomy
- Sheet
- Drag Handle
- Scrim (in modal bottom sheets)
More details on anatomy items in the component guidelines.
Key properties
Sheet attributes
| Element | Attribute | Related method(s) | Default value |
|---|---|---|---|
| Color | app:backgroundTint |
N/A | ?attr/colorSurfaceContainerLow |
| Shape | app:shapeAppearance |
N/A | ?attr/shapeAppearanceCornerExtraLarge |
| Elevation | android:elevation |
N/A | 1dp |
| Max width | android:maxWidth |
setMaxWidthgetMaxWidth |
640dp |
| Max height | android:maxHeight |
setMaxHeightgetMaxHeight |
N/A |
Behavior attributes
More information about these attributes and how to use them in the setting behavior section.
| Behavior | Related method(s) | Default value |
|---|---|---|
app:behavior_peekHeight |
setPeekHeightgetPeekHeight |
auto |
app:behavior_hideable |
setHideableisHideable |
false for standardtrue for modal |
app:behavior_skipCollapsed |
setSkipCollapsedgetSkipCollapsed |
false |
app:behavior_fitToContents |
setFitToContentsisFitToContents |
true |
app:behavior_draggable |
setDraggableisDraggable |
true |
app:behavior_draggableOnNestedScroll |
setDraggableOnNestedScrollisDraggableOnNestedScroll |
true |
app:behavior_halfExpandedRatio |
setHalfExpandedRatiogetHalfExpandedRatio |
0.5 |
app:behavior_expandedOffset |
setExpandedOffsetgetExpandedOffset |
0dp |
app:behavior_significantVelocityThreshold |
setSignificantVelocityThreshold getSignificantVelocityThreshold |
500 pixels/s |
To save behavior on configuration change:
| Attribute | Related method(s) | Default value |
|---|---|---|
app:behavior_saveFlags |
setSaveFlagsgetSaveFlags |
SAVE_NONE |
Styles
| Element | Default value |
|---|---|
| Default style (modal) | @style/Widget.Material3.BottomSheet.Modal |
Default style theme attribute:?attr/bottomSheetStyle
Note: The ?attr/bottomSheetStyle default style theme attribute is for
modal
bottom sheets only. There is no default style theme attribute for standard
bottom sheets, because BottomSheetBehaviors don’t have a designated associated
View.
Theme overlays
| Element | Theme overlay |
|---|---|
| Default theme overlay | ThemeOverlay.Material3.BottomSheetDialog |
Default theme overlay attribute: ?attr/bottomSheetDialogTheme
For the full list, see styles, attrs, and themes and theme overlays.
Variants of bottom sheets
Standard bottom sheet
Standard bottom sheets co-exist with the screen’s main UI region and allow for
simultaneously viewing and interacting with both regions. They are commonly used
to keep a feature or secondary content visible on screen when content in the
main UI region is frequently scrolled or panned.
[`BottomSheetBehavior`](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetBehavior)
is applied to a child of
[CoordinatorLayout](https://developer.android.com/reference/androidx/coordinatorlayout/widget/CoordinatorLayout)
to make that child a **persistent bottom sheet**, which is a view that comes up
from the bottom of the screen, elevated over the main content. It can be dragged
vertically to expose more or less content.
API and source code:
* `BottomSheetBehavior`
* [Class definition](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetBehavior)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/BottomSheetBehavior.java)
##### Standard bottom sheet example
The following example shows a standard bottom sheet in its collapsed and
expanded states:
Collapsed | Expanded
:-----------------------------------------------------------------------------------------: | :--------:
| 
`BottomSheetBehavior` works in tandem with `CoordinatorLayout` to let you
display content on a bottom sheet, perform enter/exit animations, respond to
dragging/swiping gestures, etc.
Apply the `BottomSheetBehavior` to a direct child `View` of `CoordinatorLayout`:
```xml
<androidx.coordinatorlayout.widget.CoordinatorLayout
...>
Modal bottom sheet
Modal bottom sheets present a set of choices while blocking interaction with the
rest of the screen. They are an alternative to inline menus and simple dialogs
on mobile devices, providing additional room for content, iconography, and
actions.
[`BottomSheetDialogFragment`](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetDialogFragment)
is a thin layer on top of the regular support library Fragment that renders your
fragment as a **modal bottom sheet**, fundamentally acting as a dialog.
Modal bottom sheets render a shadow on the content below them, to indicate that
they are modal. If the content outside of the dialog is tapped, the bottom sheet
is dismissed. Modal bottom sheets can be dragged vertically and dismissed by
sliding them down completely.
API and source code:
* `BottomSheetDialogFragment`
* [Class definition](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetDialogFragment)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/BottomSheetDialogFragment.java)
##### Modal bottom sheet example
The following example shows a modal bottom sheet in its collapsed and expanded
states:
Collapsed | Expanded
:-----------------------------------------------------------------------------------: | :--------:
| 
First, subclass `BottomSheetDialogFragment` and overwrite `onCreateView` to
provide a layout for the contents of the sheet (in this example, it's
`modal_bottom_sheet_content.xml`):
```kt
class ModalBottomSheet : BottomSheetDialogFragment() {
override fun onCreateView(
inflater: LayoutInflater,
container: ViewGroup?,
savedInstanceState: Bundle?
): View? = inflater.inflate(R.layout.modal_bottom_sheet_content, container, false)
companion object {
const val TAG = "ModalBottomSheet"
}
}
```
Then, inside an `AppCompatActivity`, to show the bottom sheet:
```kt
val modalBottomSheet = ModalBottomSheet()
modalBottomSheet.show(supportFragmentManager, ModalBottomSheet.TAG)
```
`BottomSheetDialogFragment` is a subclass of `AppCompatFragment`, which means
you need to use `Activity.getSupportFragmentManager()`.
**Note:** Don't call `setOnCancelListener` or `setOnDismissListener` on a
`BottomSheetDialogFragment`. You can override
`onCancel(DialogInterface)` or `onDismiss(DialogInterface)` if necessary.
`BottomSheetDialogFragment` wraps the view in a `BottomSheetDialog`, which has
its own `BottomSheetBehavior`. You can define your own `BottomSheetBehavior`
through overriding `onCreateDialog`.
**Note:** If overriding `onCreateDialog`, you should not override
`onCreateView`.
```kt
import android.view.View
import com.google.android.material.bottomsheet.BottomSheetBehavior
class ModalBottomSheet : BottomSheetDialogFragment() {
override fun onCreateDialog(
savedInstanceState: Bundle?,
): Dialog {
val bottomSheetDialog: BottomSheetDialog =
BottomSheetDialog(
getContext(), R.style.ThemeOverlay_Catalog_BottomSheetDialog_Scrollable
)
bottomSheetDialog.setContentView(R.layout.bottom_sheet_content)
// Set behavior attributes
bottomSheetDialog.getBehavior().setPeekHeight(123)
return bottomSheetDialog
}
}
```
Theming bottom sheets
Bottom sheets support
[Material Theming](https://material.io/components/sheets-bottom#theming), which
can customize color and shape.
#### Bottom sheet theming example
API and source code:
* `BottomSheetBehavior`
* [Class definition](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetBehavior)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/BottomSheetBehavior.java)
* `BottomSheetDialogFragment`
* [Class definition](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetDialogFragment)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/BottomSheetDialogFragment.java)
The following example shows a bottom sheet with Material Theming, in its
collapsed and expanded states.
#### Implementing bottom sheet theming
Setting the theme attribute `bottomSheetDialogTheme` to your custom
`ThemeOverlay` will affect all bottom sheets.
In `res/values/themes.xml`:
```xml
```
In `res/values/styles.xml`:
```xml
```
**Note:** The benefit of using a custom `ThemeOverlay` is that any changes to
your main theme, such as updated colors, will be reflected in the bottom sheet,
as long as they're not overridden in your custom theme overlay. If you use a
custom `Theme` instead, by extending from one of the
`Theme.Material3.*.BottomSheetDialog` variants, you will have more control over
exactly what attributes are included in each, but it also means you'll have to
duplicate any changes that you've made in your main theme into your custom
theme.