BottomSheetBehavior

public class BottomSheetBehavior<V extends View>

An interaction behavior plugin for a child view of CoordinatorLayout to make it work as a bottom sheet.

To send useful accessibility events, set a title on bottom sheets that are windows or are window-like. For BottomSheetDialog use setTitle, and for BottomSheetDialogFragment use setAccessibilityPaneTitle.

For more information, see the component developer guidance and design guidelines.

Summary

Nested types

Callback for monitoring events about bottom sheets.

State persisted across instances

Constants
static final int

Peek at the 16:9 ratio keyline of its parent.
static final int

This flag will preserve all aforementioned values on configuration change.
static final int

This flag will preserve the fitToContents boolean value on configuration change.
static final int

This flag will preserve the hideable boolean value on configuration change.
static final int

This flag will not preserve the aforementioned values set at runtime if the view is destroyed and recreated.
static final int

This flag will preserve the peekHeight int value on configuration change.
static final int

This flag will preserve the skipCollapsed boolean value on configuration change.
static final int

The bottom sheet is collapsed.
static final int

The bottom sheet is dragging.
static final int

The bottom sheet is expanded.
static final int

The bottom sheet is half-expanded (used when fitToContents is false).
static final int

The bottom sheet is hidden.
static final int

The bottom sheet is settling.

Public fields
int
float
float
int
int
int

Peek height set by the user.
int
int
boolean
int

Public constructors
BottomSheetBehavior(Context context, AttributeSet attrs)

Public methods
void

Adds a callback to be notified of bottom sheet events.
float

Calculates the current offset of the bottom sheet.
void

Call this method from onBackCancelled or handleOnBackCancelled so that the back handler can cancel the back animation.
static BottomSheetBehavior<V>
<V extends View> from(V view)

A utility function to get the BottomSheetBehavior associated with the view.
int

Returns the current expanded offset.
float

Gets the ratio for the height of the BottomSheet in the STATE_HALF_EXPANDED state.
float

Gets the friction coefficient to hide the bottom sheet, or set it to the next closest expanded state.
int

Returns the bottom sheet's maximum height, or -1 if no maximum height is set.
int

Returns the bottom sheet's maximum width, or -1 if no maximum width is set.
int

Gets the height of the bottom sheet when it is collapsed.
int

Returns the save flags.
int

Returns the significant velocity threshold.
boolean

Sets whether this bottom sheet should skip the collapsed state when it is being hidden after it is expanded once.
int

Gets the current state of the bottom sheet.
void

Call this method from onBackInvoked or handleOnBackPressed so that the back handler can complete the back animation, or handle back without progress in certain cases.
boolean
boolean
boolean
boolean

Returns whether this bottom sheet should adjust it's position based on the system gesture area.
boolean

Gets whether this bottom sheet can hide when it is swiped down.
boolean

Returns whether the bottom sheet will remove its corners when it reaches the expanded state.
void
onAttachedToLayoutParams(LayoutParams layoutParams)
void
boolean
onInterceptTouchEvent(
    CoordinatorLayout parent,
    V child,
    MotionEvent event
)
boolean
onLayoutChild(CoordinatorLayout parent, V child, int layoutDirection)
boolean
onMeasureChild(
    CoordinatorLayout parent,
    V child,
    int parentWidthMeasureSpec,
    int widthUsed,
    int parentHeightMeasureSpec,
    int heightUsed
)
boolean
onNestedPreFling(
    CoordinatorLayout coordinatorLayout,
    V child,
    View target,
    float velocityX,
    float velocityY
)
void
onNestedPreScroll(
    CoordinatorLayout coordinatorLayout,
    V child,
    View target,
    int dx,
    int dy,
    int[] consumed,
    int type
)
void
onNestedScroll(
    CoordinatorLayout coordinatorLayout,
    V child,
    View target,
    int dxConsumed,
    int dyConsumed,
    int dxUnconsumed,
    int dyUnconsumed,
    int type,
    int[] consumed
)
void
onRestoreInstanceState(
    CoordinatorLayout parent,
    V child,
    Parcelable state
)
Parcelable
onSaveInstanceState(CoordinatorLayout parent, V child)
boolean
onStartNestedScroll(
    CoordinatorLayout coordinatorLayout,
    V child,
    View directTargetChild,
    View target,
    int axes,
    int type
)
void
onStopNestedScroll(
    CoordinatorLayout coordinatorLayout,
    V child,
    View target,
    int type
)
boolean
onTouchEvent(CoordinatorLayout parent, V child, MotionEvent event)
void

Removes a previously added callback.
void

This method is deprecated.

use addBottomSheetCallback and removeBottomSheetCallback instead
void
setDraggable(boolean draggable)

Sets whether this bottom sheet can be collapsed/expanded by dragging.
void
setDraggableOnNestedScroll(boolean draggableOnNestedScroll)

Sets whether this bottom sheet can be collapsed/expanded by dragging on the nested scrolling child view.
void
setExpandedOffset(int offset)

Determines the top offset of the BottomSheet in the STATE_EXPANDED state when fitsToContent is false.
void
setFitToContents(boolean fitToContents)

Sets whether the height of the expanded sheet is determined by the height of its contents, or if it is expanded in two stages (half the height of the parent container, full height of parent container).
void
setGestureInsetBottomIgnored(boolean gestureInsetBottomIgnored)

Sets whether this bottom sheet should adjust it's position based on the system gesture area on Android Q and above.
void
setHalfExpandedRatio(float ratio)

Determines the height of the BottomSheet in the STATE_HALF_EXPANDED state.
void
setHideFriction(float hideFriction)

Sets the friction coefficient to hide the bottom sheet, or set it to the next closest expanded state.
void
setHideable(boolean hideable)

Sets whether this bottom sheet can hide.
void
setMaxHeight(int maxHeight)

Sets the maximum height of the bottom sheet.
void
setMaxWidth(int maxWidth)

Sets the maximum width of the bottom sheet.
void
setPeekHeight(int peekHeight)

Sets the height of the bottom sheet when it is collapsed.
void
setSaveFlags(int flags)

Sets save flags to be preserved in bottomsheet on configuration change.
void
setShouldRemoveExpandedCorners(boolean shouldRemoveExpandedCorners)

Sets whether the bottom sheet should remove its corners when it reaches the expanded state.
void
setSignificantVelocityThreshold(int significantVelocityThreshold)

Sets the velocity threshold considered significant enough to trigger a slide to the next stable state.
void
setSkipCollapsed(boolean skipCollapsed)

Sets whether this bottom sheet should skip the collapsed state when it is being hidden after it is expanded once.
void
setState(int state)

Sets the state of the bottom sheet.
void
setUpdateImportantForAccessibilityOnSiblings(
    boolean updateImportantForAccessibilityOnSiblings
)

Sets whether the BottomSheet should update the accessibility status of its siblings when expanded.
void
startBackProgress(BackEventCompat backEvent)

Call this method from onBackStarted or handleOnBackStarted so that the back handler can initialize and start animating.
void
updateBackProgress(BackEventCompat backEvent)

Call this method from onBackProgressed or handleOnBackProgressed so that the back handler can continue animating with a new progress value.

Constants

PEEK_HEIGHT_AUTO

public static final int PEEK_HEIGHT_AUTO = -1

Peek at the 16:9 ratio keyline of its parent.

This can be used as a parameter for setPeekHeight. getPeekHeight will return this when the value is set.

SAVE_ALL

public static final int SAVE_ALL = -1

This flag will preserve all aforementioned values on configuration change.

SAVE_FIT_TO_CONTENTS

public static final int SAVE_FIT_TO_CONTENTS = 2

This flag will preserve the fitToContents boolean value on configuration change.

SAVE_HIDEABLE

public static final int SAVE_HIDEABLE = 4

This flag will preserve the hideable boolean value on configuration change.

SAVE_NONE

public static final int SAVE_NONE = 0

This flag will not preserve the aforementioned values set at runtime if the view is destroyed and recreated. The only value preserved will be the positional state, e.g. collapsed, hidden, expanded, etc. This is the default behavior.

SAVE_PEEK_HEIGHT

public static final int SAVE_PEEK_HEIGHT = 1

This flag will preserve the peekHeight int value on configuration change.

SAVE_SKIP_COLLAPSED

public static final int SAVE_SKIP_COLLAPSED = 8

This flag will preserve the skipCollapsed boolean value on configuration change.

STATE_COLLAPSED

public static final int STATE_COLLAPSED = 4

The bottom sheet is collapsed.

STATE_DRAGGING

public static final int STATE_DRAGGING = 1

The bottom sheet is dragging.

STATE_EXPANDED

public static final int STATE_EXPANDED = 3

The bottom sheet is expanded.

STATE_HALF_EXPANDED

public static final int STATE_HALF_EXPANDED = 6

The bottom sheet is half-expanded (used when fitToContents is false).

STATE_HIDDEN

public static final int STATE_HIDDEN = 5

The bottom sheet is hidden.

STATE_SETTLING

public static final int STATE_SETTLING = 2

The bottom sheet is settling.

Public fields

expandedOffset

public int expandedOffset

halfExpandedRatio

public float halfExpandedRatio

hideFriction

public float hideFriction

maxHeight

public int maxHeight

maxWidth

public int maxWidth

peekHeight

public int peekHeight

Peek height set by the user.

saveFlags

public int saveFlags

significantVelocityThreshold

public int significantVelocityThreshold

skipCollapsed

public boolean skipCollapsed

state

public int state

Public constructors

BottomSheetBehavior

public BottomSheetBehavior()

BottomSheetBehavior

public BottomSheetBehavior(Context context, AttributeSet attrs)

Public methods

addBottomSheetCallback

public void addBottomSheetCallback(
    BottomSheetBehavior.BottomSheetCallback callback
)

Adds a callback to be notified of bottom sheet events.

Parameters
BottomSheetBehavior.BottomSheetCallback callback

The callback to notify when bottom sheet events occur.

calculateSlideOffset

public float calculateSlideOffset()

Calculates the current offset of the bottom sheet. This method should be called when the child view is laid out.

Returns
float

The offset of this bottom sheet within [-1,1] range. Offset increases as this bottom sheet is moving upward. From 0 to 1 the sheet is between collapsed and expanded states and from -1 to 0 it is between hidden and collapsed states. Returns -1 if the bottom sheet is not laid out (therefore it's hidden).

cancelBackProgress

public void cancelBackProgress()

Call this method from onBackCancelled or handleOnBackCancelled so that the back handler can cancel the back animation.

from

public static BottomSheetBehavior<V> <V extends View> from(V view)

A utility function to get the BottomSheetBehavior associated with the view.

Parameters
V view

The View with BottomSheetBehavior.
Returns
BottomSheetBehavior<V>

The BottomSheetBehavior associated with the view.

getExpandedOffset

public int getExpandedOffset()

Returns the current expanded offset. If fitToContents is true, it will automatically pick the offset depending on the height of the content.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_expandedOffset

getHalfExpandedRatio

public float getHalfExpandedRatio()

Gets the ratio for the height of the BottomSheet in the STATE_HALF_EXPANDED state.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_halfExpandedRatio

getHideFriction

public float getHideFriction()

Gets the friction coefficient to hide the bottom sheet, or set it to the next closest expanded state.

Returns
float

The friction coefficient that determines the swipe velocity needed to hide or set the bottom sheet to the closest expanded state.

getMaxHeight

public int getMaxHeight()

Returns the bottom sheet's maximum height, or -1 if no maximum height is set.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_android_maxHeight

See also
setMaxHeight

getMaxWidth

public int getMaxWidth()

Returns the bottom sheet's maximum width, or -1 if no maximum width is set.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_android_maxWidth

See also
setMaxWidth

getPeekHeight

public int getPeekHeight()

Gets the height of the bottom sheet when it is collapsed.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_peekHeight

Returns
int

The height of the collapsed bottom sheet in pixels, or PEEK_HEIGHT_AUTO if the sheet is configured to peek automatically at 16:9 ratio keyline

getSaveFlags

public int getSaveFlags()

Returns the save flags.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_saveFlags

See also
setSaveFlags

getSignificantVelocityThreshold

public int getSignificantVelocityThreshold()

Returns the significant velocity threshold.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_significantVelocityThreshold

See also
setSignificantVelocityThreshold

getSkipCollapsed

public boolean getSkipCollapsed()

Sets whether this bottom sheet should skip the collapsed state when it is being hidden after it is expanded once.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_skipCollapsed

Returns
boolean

Whether the bottom sheet should skip the collapsed state.

getState

public int getState()

Gets the current state of the bottom sheet.

Returns
int

One of STATE_EXPANDED, STATE_HALF_EXPANDED, STATE_COLLAPSED, STATE_DRAGGING, or STATE_SETTLING.

handleBackInvoked

public void handleBackInvoked()

Call this method from onBackInvoked or handleOnBackPressed so that the back handler can complete the back animation, or handle back without progress in certain cases.

isDraggable

public boolean isDraggable()

isDraggableOnNestedScroll

public boolean isDraggableOnNestedScroll()

isFitToContents

public boolean isFitToContents()
Returns
boolean

whether the height of the expanded sheet is determined by the height of its contents, or if it is expanded in two stages (half the height of the parent container, full height of parent container).

isGestureInsetBottomIgnored

public boolean isGestureInsetBottomIgnored()

Returns whether this bottom sheet should adjust it's position based on the system gesture area.

isHideable

public boolean isHideable()

Gets whether this bottom sheet can hide when it is swiped down.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_hideable

Returns
boolean

true if this bottom sheet can hide.

isShouldRemoveExpandedCorners

public boolean isShouldRemoveExpandedCorners()

Returns whether the bottom sheet will remove its corners when it reaches the expanded state.

onAttachedToLayoutParams

public void onAttachedToLayoutParams(LayoutParams layoutParams)

onDetachedFromLayoutParams

public void onDetachedFromLayoutParams()

onInterceptTouchEvent

public boolean onInterceptTouchEvent(
    CoordinatorLayout parent,
    V child,
    MotionEvent event
)

onLayoutChild

public boolean onLayoutChild(CoordinatorLayout parent, V child, int layoutDirection)

onMeasureChild

public boolean onMeasureChild(
    CoordinatorLayout parent,
    V child,
    int parentWidthMeasureSpec,
    int widthUsed,
    int parentHeightMeasureSpec,
    int heightUsed
)

onNestedPreFling

public boolean onNestedPreFling(
    CoordinatorLayout coordinatorLayout,
    V child,
    View target,
    float velocityX,
    float velocityY
)

onNestedPreScroll

public void onNestedPreScroll(
    CoordinatorLayout coordinatorLayout,
    V child,
    View target,
    int dx,
    int dy,
    int[] consumed,
    int type
)

onNestedScroll

public void onNestedScroll(
    CoordinatorLayout coordinatorLayout,
    V child,
    View target,
    int dxConsumed,
    int dyConsumed,
    int dxUnconsumed,
    int dyUnconsumed,
    int type,
    int[] consumed
)

onRestoreInstanceState

public void onRestoreInstanceState(
    CoordinatorLayout parent,
    V child,
    Parcelable state
)

onSaveInstanceState

public Parcelable onSaveInstanceState(CoordinatorLayout parent, V child)

onStartNestedScroll

public boolean onStartNestedScroll(
    CoordinatorLayout coordinatorLayout,
    V child,
    View directTargetChild,
    View target,
    int axes,
    int type
)

onStopNestedScroll

public void onStopNestedScroll(
    CoordinatorLayout coordinatorLayout,
    V child,
    View target,
    int type
)

onTouchEvent

public boolean onTouchEvent(CoordinatorLayout parent, V child, MotionEvent event)

removeBottomSheetCallback

public void removeBottomSheetCallback(
    BottomSheetBehavior.BottomSheetCallback callback
)

Removes a previously added callback.

Parameters
BottomSheetBehavior.BottomSheetCallback callback

The callback to remove.

setBottomSheetCallback

public void setBottomSheetCallback(
    BottomSheetBehavior.BottomSheetCallback callback
)

Sets a callback to be notified of bottom sheet events.

Parameters
BottomSheetBehavior.BottomSheetCallback callback

The callback to notify when bottom sheet events occur.

setDraggable

public void setDraggable(boolean draggable)

Sets whether this bottom sheet can be collapsed/expanded by dragging. Note: When disabling dragging, an app will require to implement a custom way to expand/collapse the bottom sheet

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_draggable

Parameters
boolean draggable

false to prevent dragging the sheet to collapse and expand

setDraggableOnNestedScroll

public void setDraggableOnNestedScroll(boolean draggableOnNestedScroll)

Sets whether this bottom sheet can be collapsed/expanded by dragging on the nested scrolling child view. Default is true.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_draggableOnNestedScroll

Parameters
boolean draggableOnNestedScroll

false to prevent dragging the nested scrolling child view to collapse and expand the sheet

setExpandedOffset

public void setExpandedOffset(int offset)

Determines the top offset of the BottomSheet in the STATE_EXPANDED state when fitsToContent is false. The default value is 0, which results in the sheet matching the parent's top.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_expandedOffset

Parameters
int offset

an integer value greater than equal to 0, representing the STATE_EXPANDED offset. Value must not exceed the offset in the half expanded state.

setFitToContents

public void setFitToContents(boolean fitToContents)

Sets whether the height of the expanded sheet is determined by the height of its contents, or if it is expanded in two stages (half the height of the parent container, full height of parent container). Default value is true.

Parameters
boolean fitToContents

whether or not to fit the expanded sheet to its contents.

setGestureInsetBottomIgnored

public void setGestureInsetBottomIgnored(boolean gestureInsetBottomIgnored)

Sets whether this bottom sheet should adjust it's position based on the system gesture area on Android Q and above.

Note: the bottom sheet will only adjust it's position if it would be unable to be scrolled upwards because the peekHeight is less than the gesture inset margins,(because that would cause a gesture conflict), gesture navigation is enabled, and this ignoreGestureInsetBottom flag is false.

setHalfExpandedRatio

public void setHalfExpandedRatio(float ratio)

Determines the height of the BottomSheet in the STATE_HALF_EXPANDED state. The material guidelines recommended a value of 0.5, which results in the sheet filling half of the parent. The height of the BottomSheet will be smaller as this ratio is decreased and taller as it is increased. The default value is 0.5.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_halfExpandedRatio

Parameters
float ratio

a float between 0 and 1, representing the STATE_HALF_EXPANDED ratio.

setHideFriction

public void setHideFriction(float hideFriction)

Sets the friction coefficient to hide the bottom sheet, or set it to the next closest expanded state.

Parameters
float hideFriction

The friction coefficient that determines the swipe velocity needed to hide or set the bottom sheet to the closest expanded state.

setHideable

public void setHideable(boolean hideable)

Sets whether this bottom sheet can hide.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_hideable

Parameters
boolean hideable

true to make this bottom sheet hideable.

setMaxHeight

public void setMaxHeight(int maxHeight)

Sets the maximum height of the bottom sheet. This method should be called before show in order for the height to be adjusted as expected.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_android_maxHeight

Parameters
int maxHeight

The maximum height in pixels to be set
See also
getMaxHeight

setMaxWidth

public void setMaxWidth(int maxWidth)

Sets the maximum width of the bottom sheet. The layout will be at most this dimension wide. This method should be called before show in order for the width to be adjusted as expected.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_android_maxWidth

Parameters
int maxWidth

The maximum width in pixels to be set
See also
getMaxWidth

setPeekHeight

public void setPeekHeight(int peekHeight)

Sets the height of the bottom sheet when it is collapsed.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_peekHeight

Parameters
int peekHeight

The height of the collapsed bottom sheet in pixels, or PEEK_HEIGHT_AUTO to configure the sheet to peek automatically at 16:9 ratio keyline.

setSaveFlags

public void setSaveFlags(int flags)

Sets save flags to be preserved in bottomsheet on configuration change.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_saveFlags

Parameters
int flags

bitwise int of SAVE_PEEK_HEIGHT, SAVE_FIT_TO_CONTENTS, SAVE_HIDEABLE, SAVE_SKIP_COLLAPSED, SAVE_ALL and SAVE_NONE.
See also
getSaveFlags

setShouldRemoveExpandedCorners

public void setShouldRemoveExpandedCorners(boolean shouldRemoveExpandedCorners)

Sets whether the bottom sheet should remove its corners when it reaches the expanded state.

If false, the bottom sheet will only remove its corners if it is expanded and reaches the top of the screen.

setSignificantVelocityThreshold

public void setSignificantVelocityThreshold(int significantVelocityThreshold)

Sets the velocity threshold considered significant enough to trigger a slide to the next stable state.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_significantVelocityThreshold

Parameters
int significantVelocityThreshold

The velocity threshold that warrants a vertical swipe.
See also
getSignificantVelocityThreshold

setSkipCollapsed

public void setSkipCollapsed(boolean skipCollapsed)

Sets whether this bottom sheet should skip the collapsed state when it is being hidden after it is expanded once. Setting this to true has no effect unless the sheet is hideable.

ref com.google.android.material.R.styleable#BottomSheetBehavior_Layout_behavior_skipCollapsed

Parameters
boolean skipCollapsed

True if the bottom sheet should skip the collapsed state.

setState

public void setState(int state)

Sets the state of the bottom sheet. The bottom sheet will transition to that state with animation.

Parameters
int state

One of STATE_COLLAPSED, STATE_EXPANDED, STATE_HIDDEN, or STATE_HALF_EXPANDED.

setUpdateImportantForAccessibilityOnSiblings

public void setUpdateImportantForAccessibilityOnSiblings(
    boolean updateImportantForAccessibilityOnSiblings
)

Sets whether the BottomSheet should update the accessibility status of its siblings when expanded.

Set this to true if the expanded state of the sheet blocks access to siblings (e.g., when the sheet expands over the full screen).

startBackProgress

public void startBackProgress(BackEventCompat backEvent)

Call this method from onBackStarted or handleOnBackStarted so that the back handler can initialize and start animating.

Note that this must be called prior to calling updateBackProgress.

updateBackProgress

public void updateBackProgress(BackEventCompat backEvent)

Call this method from onBackProgressed or handleOnBackProgressed so that the back handler can continue animating with a new progress value.