PlaceholderState

public class PlaceholderState internal constructor(
    private val isContentReady: State<() -> Boolean>,
    private val maxScreenDimension: Float,
    private val isReduceMotionEnabled: Boolean,
)

A state object that can be used to control placeholders. Placeholders are used when the content that needs to be displayed in a component is not yet available, e.g. it is loading asynchronously.

A PlaceholderState should be created for each component that has placeholder data. The state is used to coordinate all of the different placeholder effects and animations.

Placeholder has a number of different effects designed to work together. Modifier.placeholder draws a placeholder shape on top of content that is waiting to load. There can be multiple placeholders in a component. Modifier.placeholderShimmer does a shimmer animation over the whole component that includes the placeholders. There should only be one placeholderShimmer for each component.

NOTE: The order of modifiers is important. If you are adding both Modifier.placeholder and Modifier.placeholderShimmer to the same composable then the shimmer must be before in the modifier chain. Example of Text composable with both placeholderShimmer and placeholder modifiers.

Background placeholder effects are used to mask the background of components like chips and cards until all of the data has loaded. Use PlaceholderDefaults.placeholderChipColors PlaceholderDefaults.placeholderBackgroundBrush and PlaceholderDefaults.painterWithPlaceholderOverlayBackgroundBrush to draw the component background.

Once all of the components content is loaded the shimmer will stop and a wipe off animation will remove the placeholders.

Properties

absoluteProgression

val absoluteProgression =
            ((frameMillis.longValue - startOfWipeOffAnimation)
                    .coerceAtMost(PLACEHOLDER_WIPE_OFF_PROGRESSION_DURATION_MS)
                    .toFloat() / PLACEHOLDER_WIPE_OFF_PROGRESSION_DURATION_MS)
                .coerceAtMost(1f)

The current value of the placeholder wipe-off visual effect gradient progression. The progression is a 45 degree angle sweep across the whole screen running from outside of the Top|Left of the screen to Bottom|Right used as the anchor for wipe-off gradient effects.

The progression represents the x and y coordinates in pixels of the Top|Left part of the gradient that flows across the screen. The progression will start at -maxScreenDimension (max of height/width to create a 45 degree angle) 1.75f and progress to the maximumScreenDimension 0.75f.

The time taken for this progression to reach the edge of visible screen is PLACEHOLDER_WIPE_OFF_PROGRESSION_DURATION_MS

easedProgression

val easedProgression = wipeOffInterpolator.transform(absoluteProgression)

Functions

startPlaceholderAnimation

public suspend fun startPlaceholderAnimation()

Start the animation of the placeholder state.