Skip to content

Latest commit

 

History

History
206 lines (149 loc) · 7.39 KB

SideSheet.md

File metadata and controls

206 lines (149 loc) · 7.39 KB
Raw

Side Sheets

Side sheets are surfaces containing supplementary content that are anchored to the side of the screen.

See Bottom Sheet documentation for documentation about bottom sheets.

Contents

Using side sheets

Before you can use Material side sheets, you need to add a dependency to the Material Components for Android library. For more information, go to the Getting started page.

Standard side sheet basic usage:

<androidx.coordinatorlayout.widget.CoordinatorLayout
  ...>

  <FrameLayout
    ...
    android:id="@+id/standard_side_sheet"
    app:layout_behavior="com.google.android.material.sidesheet.SideSheetBehavior">

    <!-- Side sheet content. -->

  </FrameLayout>

</androidx.coordinatorlayout.widget.CoordinatorLayout>

Setting behavior

There are several attributes that can be used to adjust the behavior of standard side sheets.

Behavior attributes can be applied to standard side sheets in xml by setting them on a child View set to app:layout_behavior, or programmatically:

val standardSideSheetBehavior = SideSheetBehavior.from(standardSideSheet)
// Use this to programmatically apply behavior attributes

More information about these attributes and their default values is available in the behavior attributes section.

Setting state

Standard side sheets have the following states:

  • STATE_EXPANDED: The side sheet is visible at its maximum height and it is neither dragging nor settling (see below).
  • STATE_HIDDEN: The side sheet is no longer visible and can only be re-shown programmatically.
  • STATE_DRAGGING: The user is actively dragging the side sheet.
  • STATE_SETTLING: The side sheet is settling to a specific height after a drag/swipe gesture. This will be the peek height, expanded height, or 0, in case the user action caused the side sheet to hide.

You can set a state on the side sheet:

sideSheetBehavior.state = Sheet.STATE_HIDDEN

Note: STATE_SETTLING and STATE_DRAGGING should not be set programmatically.

Standard side sheet

Standard side 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.

SideSheetBehavior is applied to a child of CoordinatorLayout to make that child a standard side sheet, which is a view that comes up from the side of the screen, elevated over the main content. It can be dragged vertically to expose more or less content.

API and source code:

Standard side sheet example

The following example shows a standard side sheet in its collapsed and expanded states:

SideSheetBehavior works in tandem with CoordinatorLayout to let you display content in a side sheet, perform enter/exit animations, respond to dragging/swiping gestures, and more.

Apply the SideSheetBehavior to a direct child View of CoordinatorLayout:

<androidx.coordinatorlayout.widget.CoordinatorLayout
  ...>

  <LinearLayout
    android:id="@+id/standard_side_sheet"
    style="@style/Widget.Material3.SideSheet"
    android:layout_width="256dp"
    android:layout_height="match_parent"
    android:orientation="vertical"
    app:layout_behavior="com.google.android.material.sidesheet.SideSheetBehavior">

    <!-- Side sheet contents. -->
    <TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/title"
    .../>

    <TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/supporting_text"
    .../>

    <Button
    android:id="@+id/sidesheet_button"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/action"
    .../>

  </LinearLayout>

</androidx.coordinatorlayout.widget.CoordinatorLayout>

In this example, the side sheet is the LinearLayout.

Anatomy and key properties

Side sheets have a sheet and content.

Sheet attributes

Element Attribute Related method(s) Default value
Color app:backgroundTint N/A ?attr/colorSurface
Shape app:shapeAppearance N/A ?attr/shapeAppearanceLargeComponent
Elevation android:elevation N/A 0dp
Max width android:maxWidth setMaxWidth
getMaxWidth		 N/A
Max height android:maxHeight setMaxHeight
getMaxHeight		 N/A

Behavior attributes

More info about these attributes and how to use them in the setting behavior section.

Behavior Related method(s) Default value
app:behavior_draggable setDraggable
isDraggable		 true

Styles

Element Value
Standard side sheet style @style/Widget.Material3.SideSheet

Note: There is no default style theme attribute for standard side sheets, because SideSheetBehaviors don't have a designated associated View.

See the full list of styles, and attributes.

Theming side sheets

Side sheets support Material Theming, which can customize color and shape.

Side sheet theming example

API and source code: