# androidx.compose.runtime.retain

Common/All

## Interfaces

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver` | Objects implementing this interface are notified of their usage in `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedEffectResult` | The return type of a built `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedEffect.composable#RetainedEffect(kotlin.Function1)`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` | A `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` acts as a storage area for objects being retained. | Cmn |

## Classes

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` | A `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` is the default implementation of `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` that can be used to define custom retention periods in the composition hierarchy. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedEffectScope` | Receiver scope for `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedEffect.composable#RetainedEffect(kotlin.Function1)` that offers the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedEffectScope#onRetire(kotlin.Function0)` clause that should be the last statement in any call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedEffect.composable#RetainedEffect(kotlin.Function1)`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry` | A `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry` creates and manages `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` instances for collections of items. | Cmn |

## Objects

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ForgetfulRetainedValuesStore` | The `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ForgetfulRetainedValuesStore` is an implementation of `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` that is incapable of retaining any exited values. | Cmn |

## Composables

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/LocalRetainedValuesStoreProvider.composable` | Installs the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` over the provided `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/package-summary#LocalRetainedValuesStoreProvider(androidx.compose.runtime.retain.RetainedValuesStore,kotlin.Function0)` such that all values retained in the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/package-summary#LocalRetainedValuesStoreProvider(androidx.compose.runtime.retain.RetainedValuesStore,kotlin.Function0)` lambda are owned by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/package-summary#LocalRetainedValuesStoreProvider(androidx.compose.runtime.retain.RetainedValuesStore,kotlin.Function0)`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedEffect.composable` |   | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable` | Remember the value produced by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/package-summary#retain(kotlin.Function0)` and retain it in the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/package-summary#LocalRetainedValuesStore()`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retainManagedRetainedValuesStore.composable` | Retains a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retainRetainedValuesStoreRegistry.composable` | Returns a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)`ed instance of a new `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/withLocalRetainedValuesStore.composable` | Installs the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/package-summary#withLocalRetainedValuesStore(androidx.compose.runtime.retain.RetainedValuesStore,kotlin.Function0)` over the provided `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/package-summary#withLocalRetainedValuesStore(androidx.compose.runtime.retain.RetainedValuesStore,kotlin.Function0)` and returns the result of the lambda. | Cmn |

## Top-level properties summary

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ProvidableCompositionLocal<https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore>` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/package-summary#LocalRetainedValuesStore()` The `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` in which `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` values will be tracked in. | Cmn |

## Top-level properties

### LocalRetainedValuesStore

Cmn Artifact: [androidx.compose.runtime:runtime-retain](https://developer.android.com/jetpack/androidx/releases/compose-runtime) [View Source](https://cs.android.com/search?q=file:androidx/compose/runtime/retain/LocalRetainedValuesStore.kt+symbol:LocalRetainedValuesStore) Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0)

```
val LocalRetainedValuesStore: ProvidableCompositionLocal<RetainedValuesStore>
```

The `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` in which `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` values will be tracked in. Since a RetainedValuesStore controls retention scenarios and signals when to start and end the retention of objects removed from composition, a composition hierarchy may have several RetainedValuesStores to introduce retention periods to specific pieces of content.

The default implementation is a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ForgetfulRetainedValuesStore` that causes `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` to behave the same as `https://developer.android.com/reference/kotlin/androidx/compose/runtime/remember.composable#remember(kotlin.Function0)`. On Android, a lifecycle-aware `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` is installed at the root of the composition that retains values across configuration changes.

If this CompositionLocal is updated, all values previously returned by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` will be adopted to the new store and will follow the new store's retention lifecycle.

Always prefer `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/LocalRetainedValuesStoreProvider.composable#LocalRetainedValuesStoreProvider(androidx.compose.runtime.retain.RetainedValuesStore,kotlin.Function0)` to setting this local directly. This local is exposed providable as an escape hatch for installing a platform- or library-specific `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/package-summary#LocalRetainedValuesStore()` at the root of the hierarchy and for testing custom `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` implementations. Stores installed through this local directly will NOT receive the default calls into `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#onContentEnteredComposition()` and `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#onContentExitComposition()` provided by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/LocalRetainedValuesStoreProvider.composable#LocalRetainedValuesStoreProvider(androidx.compose.runtime.retain.RetainedValuesStore,kotlin.Function0)`.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/LocalRetainedValuesStoreProvider.composable#LocalRetainedValuesStoreProvider(androidx.compose.runtime.retain.RetainedValuesStore,kotlin.Function0)` |   |