# AmbientModeManager

Artifact: [androidx.wear.compose:compose-foundation](https://developer.android.com/jetpack/androidx/releases/wear-compose) [View Source](https://cs.android.com/search?q=file:androidx/wear/compose/foundation/LocalAmbientModeManager.kt+class:androidx.wear.compose.foundation.AmbientModeManager) Added in [1.6.0-beta01](https://developer.android.com/jetpack/androidx/releases/wear-compose#1.6.0-beta01)


```
interface AmbientModeManager
```

<br />

*** ** * ** ***

## Summary

| ### Public functions |
|---|---|
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientModeManager#withAmbientTick(kotlin.Function0)(block: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Suspends the calling coroutine and waits for the next delivered "ambient tick". |

| ### Public properties |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientMode` | `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientModeManager#currentAmbientMode()` The current state of the display, which is either `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientMode.Interactive` or `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientMode.Ambient`. |

| ### Extension functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientModeManager.https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientModeManager#(androidx.wear.compose.foundation.AmbientModeManager).AmbientTickEffect(kotlin.Function0)(block: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` A convenience extension that performs recurrent, battery-efficient UI updates when the device is in `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientMode.Ambient`. |

## Public functions

### withAmbientTick

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

```
suspend fun withAmbientTick(block: () -> Unit): Unit
```

Suspends the calling coroutine and waits for the next delivered "ambient tick".

When the device is in `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientMode.Ambient`, the system only provides updates at infrequent intervals (typically once per minute) to preserve battery life. This function allows a coroutine to pause and resume execution specifically when that tick is received.

The provided `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientModeManager#withAmbientTick(kotlin.Function0)` will be executed synchronously when the tick occurs, and any state updates performed within it will be reflected on the ambient screen.

This function should typically be used within a looping `https://developer.android.com/reference/kotlin/androidx/compose/runtime/package-summary#LaunchedEffect(kotlin.coroutines.SuspendFunction1)` that runs only when `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientModeManager#currentAmbientMode()` is `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientMode.Ambient`.

```kotlin
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.wear.compose.foundation.AmbientMode
import androidx.wear.compose.foundation.AmbientTickEffect
import androidx.wear.compose.foundation.LocalAmbientModeManager
import androidx.wear.compose.foundation.rememberAmbientModeManager
import androidx.wear.compose.material.Text

// **Best Practice Note:** In a production application, the AmbientModeManager should be
// instantiated and provided at the highest level of the Compose hierarchy (typically in
// the host Activity's setContent block) using a CompositionLocalProvider. This ensures
// proper lifecycle management and broad accessibility.

// For this self-contained demo, AmbientModeManager is created and provided locally:
val activityAmbientModeManager = rememberAmbientModeManager()
CompositionLocalProvider(LocalAmbientModeManager provides activityAmbientModeManager) {
    var counter by remember { mutableIntStateOf(0) }

    val ambientModeManager = LocalAmbientModeManager.current
    ambientModeManager?.AmbientTickEffect {
        // While device is in ambient mode, update counter in onAmbientTick approx. every minute
        counter++
    }

    val ambientMode = ambientModeManager?.currentAmbientMode
    if (ambientMode is AmbientMode.Interactive) {
        // While device is not in ambient mode, update counter approx. every second
        LaunchedEffect(Unit) {
            while (true) {
                delay(1000L)
                counter++
            }
        }
    }

    Column(
        verticalArrangement = Arrangement.Center,
        horizontalAlignment = Alignment.CenterHorizontally,
        modifier = Modifier.fillMaxSize(),
    ) {
        val ambientModeName =
            when (ambientMode) {
                is AmbientMode.Interactive -> "Interactive"
                is AmbientMode.Ambient -> "Ambient"
                else -> "Unknown"
            }

        val updateInterval = if (ambientMode is AmbientMode.Ambient) "minute" else "second"
        val color = if (ambientMode is AmbientMode.Ambient) Color.Gray else Color.Yellow

        Text(text = "$ambientModeName Mode", color = color)
        Text(text = "Updates every $updateInterval")
        Text(text = "$counter")
    }
}
```

| Parameters |
|---|---|
| `block: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The state update logic to execute immediately upon receiving the ambient tick. |

## Public properties

### currentAmbientMode

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

```
val currentAmbientMode: AmbientMode
```

The current state of the display, which is either `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientMode.Interactive` or `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientMode.Ambient`.

This property should be backed by Compose's Snapshot State system. Reading this value inside a composable function should automatically subscribe the composable to state changes and trigger a recomposition when the ambient mode changes.

## Extension functions

### AmbientTickEffect

Artifact: [androidx.wear.compose:compose-foundation](https://developer.android.com/jetpack/androidx/releases/wear-compose) [View Source](https://cs.android.com/search?q=file:androidx/wear/compose/foundation/LocalAmbientModeManager.kt+function:AmbientTickEffect)

```
@Composable
fun AmbientModeManager.AmbientTickEffect(block: () -> Unit): Unit
```

A convenience extension that performs recurrent, battery-efficient UI updates when the device is in `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientMode.Ambient`.

This extension handles the boilerplate for ambient tick synchronization: it automatically launches and manages a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/package-summary#LaunchedEffect(kotlin.coroutines.SuspendFunction1)` that repeatedly suspends using withAmbientTick to align state updates with the system's infrequent ambient tick schedule.

The internal loop automatically terminates when the device returns to `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/AmbientMode.Interactive`.

**Efficiency Note:** The `https://developer.android.com/reference/kotlin/androidx/wear/compose/foundation/package-summary#(androidx.wear.compose.foundation.AmbientModeManager).AmbientTickEffect(kotlin.Function0)` lambda should only update the minimal `https://developer.android.com/reference/kotlin/androidx/compose/runtime/State` required to prevent excessive recomposition and maximize battery life.

Example of using AmbientTickEffect:

```kotlin
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.wear.compose.foundation.AmbientMode
import androidx.wear.compose.foundation.AmbientTickEffect
import androidx.wear.compose.foundation.LocalAmbientModeManager
import androidx.wear.compose.foundation.rememberAmbientModeManager
import androidx.wear.compose.material.Text

// **Best Practice Note:** In a production application, the AmbientModeManager should be
// instantiated and provided at the highest level of the Compose hierarchy (typically in
// the host Activity's setContent block) using a CompositionLocalProvider. This ensures
// proper lifecycle management and broad accessibility.

// For this self-contained demo, AmbientModeManager is created and provided locally:
val activityAmbientModeManager = rememberAmbientModeManager()
CompositionLocalProvider(LocalAmbientModeManager provides activityAmbientModeManager) {
    var counter by remember { mutableIntStateOf(0) }

    val ambientModeManager = LocalAmbientModeManager.current
    ambientModeManager?.AmbientTickEffect {
        // While device is in ambient mode, update counter in onAmbientTick approx. every minute
        counter++
    }

    val ambientMode = ambientModeManager?.currentAmbientMode
    if (ambientMode is AmbientMode.Interactive) {
        // While device is not in ambient mode, update counter approx. every second
        LaunchedEffect(Unit) {
            while (true) {
                delay(1000L)
                counter++
            }
        }
    }

    Column(
        verticalArrangement = Arrangement.Center,
        horizontalAlignment = Alignment.CenterHorizontally,
        modifier = Modifier.fillMaxSize(),
    ) {
        val ambientModeName =
            when (ambientMode) {
                is AmbientMode.Interactive -> "Interactive"
                is AmbientMode.Ambient -> "Ambient"
                else -> "Unknown"
            }

        val updateInterval = if (ambientMode is AmbientMode.Ambient) "minute" else "second"
        val color = if (ambientMode is AmbientMode.Ambient) Color.Gray else Color.Yellow

        Text(text = "$ambientModeName Mode", color = color)
        Text(text = "Updates every $updateInterval")
        Text(text = "$counter")
    }
}
```

| Parameters |
|---|---|
| `block: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The state update logic to execute once per ambient tick. |