{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

TopAppBarState

@ExperimentalMaterial3Api
public final class TopAppBarState


A state object that can be hoisted to control and observe the top app bar state. The state is read and updated by a TopAppBarScrollBehavior implementation.

In most cases, this state will be created via rememberTopAppBarState.

Summary

Nested types

public static class TopAppBarState.Companion

Public constructors

TopAppBarState(
    float initialHeightOffsetLimit,
    float initialHeightOffset,
    float initialContentOffset
)

Public methods

final float

A value that represents the collapsed height percentage of the app bar.

final float

The total offset of the content scrolled under the top app bar.

final float

The top app bar's current height offset in pixels.

final float

The top app bar's height offset limit in pixels, which represents the limit that a top app bar is allowed to collapse to.

final float

A value that represents the percentage of the app bar area that is overlapping with the content scrolled behind it.

final void
setContentOffset(float contentOffset)

The total offset of the content scrolled under the top app bar.

final void
setHeightOffset(float heightOffset)

The top app bar's current height offset in pixels.

final void
setHeightOffsetLimit(float heightOffsetLimit)

The top app bar's height offset limit in pixels, which represents the limit that a top app bar is allowed to collapse to.

Public constructors

TopAppBarState

public TopAppBarState(
    float initialHeightOffsetLimit,
    float initialHeightOffset,
    float initialContentOffset
)
Parameters
float initialHeightOffsetLimit

the initial value for TopAppBarState.heightOffsetLimit

float initialHeightOffset

the initial value for TopAppBarState.heightOffset

float initialContentOffset

the initial value for TopAppBarState.contentOffset

Public methods

getCollapsedFraction

public final float getCollapsedFraction()

A value that represents the collapsed height percentage of the app bar.

A 0.0 represents a fully expanded bar, and 1.0 represents a fully collapsed bar (computed as heightOffset / heightOffsetLimit).

getContentOffset

public final float getContentOffset()

The total offset of the content scrolled under the top app bar.

The content offset is used to compute the overlappedFraction, which can later be read by an implementation.

This value is updated by a TopAppBarScrollBehavior whenever a nested scroll connection consumes scroll events. A common implementation would update the value to be the sum of all NestedScrollConnection.onPostScroll consumed.y values.

getHeightOffset

public final float getHeightOffset()

The top app bar's current height offset in pixels. This height offset is applied to the fixed height of the app bar to control the displayed height when content is being scrolled.

Updates to the heightOffset value are coerced between zero and heightOffsetLimit.

getHeightOffsetLimit

public final float getHeightOffsetLimit()

The top app bar's height offset limit in pixels, which represents the limit that a top app bar is allowed to collapse to.

Use this limit to coerce the heightOffset value when it's updated.

getOverlappedFraction

public final float getOverlappedFraction()

A value that represents the percentage of the app bar area that is overlapping with the content scrolled behind it.

A 0.0 indicates that the app bar does not overlap any content, while 1.0 indicates that the entire visible app bar area overlaps the scrolled content.

setContentOffset

public final void setContentOffset(float contentOffset)

The total offset of the content scrolled under the top app bar.

The content offset is used to compute the overlappedFraction, which can later be read by an implementation.

This value is updated by a TopAppBarScrollBehavior whenever a nested scroll connection consumes scroll events. A common implementation would update the value to be the sum of all NestedScrollConnection.onPostScroll consumed.y values.

setHeightOffset

public final void setHeightOffset(float heightOffset)

The top app bar's current height offset in pixels. This height offset is applied to the fixed height of the app bar to control the displayed height when content is being scrolled.

Updates to the heightOffset value are coerced between zero and heightOffsetLimit.

setHeightOffsetLimit

public final void setHeightOffsetLimit(float heightOffsetLimit)

The top app bar's height offset limit in pixels, which represents the limit that a top app bar is allowed to collapse to.

Use this limit to coerce the heightOffset value when it's updated.