# PlaceholderState

# PlaceholderState

Artifact:[androidx.wear.compose:compose-material](https://developer.android.com/jetpack/androidx/releases/wear-compose)  
[View Source](https://cs.android.com/search?q=file:androidx/wear/compose/material/Placeholder.kt+class:androidx.wear.compose.material.PlaceholderState)  
Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/wear-compose#1.1.0)

<br />

```
@ExperimentalWearMaterialApi
class PlaceholderState
```

<br />

*** ** * ** ***

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](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/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](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/package-summary#(androidx.compose.ui.Modifier).placeholder(androidx.wear.compose.material.PlaceholderState,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color))draws a placeholder shape on top of content that is waiting to load. There can be multiple placeholders in a component.[Modifier.placeholderShimmer](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/package-summary#(androidx.compose.ui.Modifier).placeholderShimmer(androidx.wear.compose.material.PlaceholderState,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color))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](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/package-summary#(androidx.compose.ui.Modifier).placeholder(androidx.wear.compose.material.PlaceholderState,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color))and[Modifier.placeholderShimmer](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/package-summary#(androidx.compose.ui.Modifier).placeholderShimmer(androidx.wear.compose.material.PlaceholderState,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color))to the same composable then the shimmer must be before in the modifier chain. Example of[Text](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/package-summary#Text(kotlin.String,androidx.compose.ui.Modifier,androidx.compose.ui.graphics.Color,androidx.compose.ui.unit.TextUnit,androidx.compose.ui.text.font.FontStyle,androidx.compose.ui.text.font.FontWeight,androidx.compose.ui.text.font.FontFamily,androidx.compose.ui.unit.TextUnit,androidx.compose.ui.text.style.TextDecoration,androidx.compose.ui.text.style.TextAlign,androidx.compose.ui.unit.TextUnit,androidx.compose.ui.text.style.TextOverflow,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Function1,androidx.compose.ui.text.TextStyle))composable with both placeholderShimmer and placeholder modifiers.  

```kotlin
import androidx.compose.foundation.layout.width
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.wear.compose.material.Text
import androidx.wear.compose.material.placeholder
import androidx.wear.compose.material.placeholderShimmer
import androidx.wear.compose.material.rememberPlaceholderState

var labelText by remember { mutableStateOf("") }
val chipPlaceholderState = rememberPlaceholderState { labelText.isNotEmpty() }

Text(
    text = labelText,
    overflow = TextOverflow.Ellipsis,
    textAlign = TextAlign.Center,
    modifier =
        Modifier.width(90.dp)
            .placeholderShimmer(chipPlaceholderState)
            .placeholder(chipPlaceholderState),
)

// Simulate content loading
LaunchedEffect(Unit) {
    delay(3000)
    labelText = "A label"
}
if (!chipPlaceholderState.isShowContent) {
    LaunchedEffect(chipPlaceholderState) { chipPlaceholderState.startPlaceholderAnimation() }
}
```

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](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/PlaceholderDefaults#placeholderBackgroundBrush(androidx.wear.compose.material.PlaceholderState,androidx.compose.ui.graphics.Color))and[PlaceholderDefaults.painterWithPlaceholderOverlayBackgroundBrush](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/PlaceholderDefaults#painterWithPlaceholderOverlayBackgroundBrush(androidx.wear.compose.material.PlaceholderState,androidx.compose.ui.graphics.painter.Painter,androidx.compose.ui.graphics.Color))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.

## Summary

|                                  ### Public functions                                   |
|-----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `suspend `[Unit](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html) | [startPlaceholderAnimation](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/PlaceholderState#startPlaceholderAnimation())`()` Start the animation of the placeholder state. |

|                                ### Public properties                                |
|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Boolean](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html) | [isShowContent](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/PlaceholderState#isShowContent()) Returns true if the placeholder content should be shown with no placeholders effects and false if either the placeholder or the wipe-off effect are being shown.                                                                       |
| [Boolean](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html) | [isWipeOff](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/PlaceholderState#isWipeOff()) Should only be called when[isShowContent](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/PlaceholderState#isShowContent())is false.                                                                             |
| [Float](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html)     | `@`[ExperimentalWearMaterialApi](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/ExperimentalWearMaterialApi) [placeholderProgression](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/PlaceholderState#placeholderProgression()) The current value of the placeholder visual effect gradient progression. |

## Public functions

### startPlaceholderAnimation

Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/wear-compose#1.1.0)  

```
suspend fun startPlaceholderAnimation(): Unit
```

Start the animation of the placeholder state.  

## Public properties

### isShowContent

Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/wear-compose#1.1.0)  

```
val isShowContent: Boolean
```

Returns true if the placeholder content should be shown with no placeholders effects and false if either the placeholder or the wipe-off effect are being shown.  

### isWipeOff

Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/wear-compose#1.1.0)  

```
val isWipeOff: Boolean
```

Should only be called when[isShowContent](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/PlaceholderState#isShowContent())is false. Returns true if the wipe-off effect that reveals content should be shown and false if the placeholder effect should be shown.  

### placeholderProgression

Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/wear-compose#1.1.0)  

```
@ExperimentalWearMaterialApi
val placeholderProgression: Float
```

The current value of the placeholder visual effect gradient progression. The progression gives the x coordinate to be applied to the placeholder gradient as it moves across the screen. Starting off screen to the left and progressing across the screen and finishing off the screen to the right after[PLACEHOLDER_SHIMMER_DURATION_MS](https://developer.android.com/reference/kotlin/androidx/wear/compose/material/package-summary#PLACEHOLDER_SHIMMER_DURATION_MS()).