# RetainedValuesStoreRegistry

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/RetainedValuesStoreRegistry.kt+class:androidx.compose.runtime.retain.RetainedValuesStoreRegistry) Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0) Common/All
- Cmn

  ```
  class 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. This is desirable for components that swap in and out children where each child should be able to retain values when it becomes removed from the composition hierarchy.

To use this class, wrap your content in `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)` with a unique key. Each content block wrapped in this way will receive a unique `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` that retains values when the content is removed from the composition hierarchy. Values are retained for as removed content block until either the registry is `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#dispose()` or its key is `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChild(kotlin.Any)` from this registry.

When a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry` is no longer used, you must call `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#dispose()` before the provider is garbage collected. This ensures that all retained values are correctly retired. Failure to do so may result in leaked memory from undispatched `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetired()` callbacks. Instances created by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry` are automatically disposed when the provider stops being retained.

This registry is intended to be used for managing multiple `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` instances, for child composables that enter and exit the composition at different times and should retain values separately. For example, this component may be used with navigation containers, lists, etc.

```kotlin
import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material.Icon
import androidx.compose.material.IconButton
import androidx.compose.material.Text
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Delete
import androidx.compose.runtime.Composable
import androidx.compose.runtime.retain.LocalRetainedValuesStoreProvider
import androidx.compose.runtime.retain.retain
import androidx.compose.runtime.retain.retainRetainedValuesStoreRegistry
import androidx.compose.ui.graphics.painter.Painter

// List item that retains a value
@Composable
fun Contact(contact: Contact, deleteContact: () -> Unit) {
    Row {
        // Retain this painter to cache the contact icon in memory
        val contactIcon = retain { ContactIconPainter() }
        Image(contactIcon, "Contact icon")
        Text(contact.name)
        // Optional delete action (likely nested in a DropdownMenu)
        IconButton(onClick = deleteContact) { Icon(Icons.Default.Delete, "Delete contact") }
    }
}

@Composable
fun ContactsList(contacts: List<Contact>) {
    // Create the RetainedValuesStoreRegistry
    val retainedValuesStoreRegistry = retainRetainedValuesStoreRegistry()
    LazyColumn {
        items(contacts) { contact ->
            // Install it for an item in a list
            retainedValuesStoreRegistry.LocalRetainedValuesStoreProvider(contact.id) {
                // This contact now gets its own retain store.
                // If the store of ContactsList starts retaining exited values, this nested
                // store will too. If this contact leaves and re-enters composition, it will
                // keep its previously retained values.
                Contact(
                    contact = contact,
                    deleteContact = {
                        // Call into the contacts provider to delete the contact
                        // ...
                        //
                        // Optional: Purge child stores if a contact gets deleted. This is a
                        // "best effort" when a contact is deleted and might not capture all
                        // deletions. If we miss a deletion, we'll continue retaining for that
                        // contact until the list is retired. If this is a large pool of
                        // objects, you may choose to be more aggressive about how you clear
                        // keys from the registry.
                        retainedValuesStoreRegistry.clearChild(contact.id)
                    },
                )
            }
        }
    }
}
```

## Summary

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#RetainedValuesStoreRegistry()()` | Cmn |

| ### Public 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/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)(key: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?, content: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Installs child `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)` that should be retained under the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChild(kotlin.Any)(key: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?)` Removes the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` for the child with the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChild(kotlin.Any)` from this `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChildren(kotlin.Function1)(predicate: (https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Bulk removes all child stores for which the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChildren(kotlin.Function1)` returns true. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#dispose()()` Removes all child `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore`s from this `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry` and marks it as ineligible for future use. | Cmn |

## Public constructors

### RetainedValuesStoreRegistry

Cmn Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0)

```
RetainedValuesStoreRegistry()
```

## Public functions

### LocalRetainedValuesStoreProvider

Cmn Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0)

```
@Composable
fun LocalRetainedValuesStoreProvider(key: Any?, content: @Composable () -> Unit): Unit
```

Installs child `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)` that should be retained under the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)`. `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)`s must be unique within the composition hierarchy for a given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry`.

When removed, this composable retains exited values from the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)` lambda under the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)`. When added back to the composition hierarchy, the underlying store will restore these values and dispose unused values when the composition completes.

This composable only attempts to manage the retention lifecycle for the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)` and `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)` pair. It will retain removed content indefinitely until `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChild(kotlin.Any)` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChildren(kotlin.Function1)` is invoked.

| Parameters |
|---|---|
| `key: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?` | The unique child key associated with the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)`. This key is used to identify the retention pool for objects `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` by the content composable. |
| `content: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The composable content to compose with the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` of the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)` |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#dispose()` has been called |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if the same `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)` is used twice in the composition hierarchy under this registry. |

### clearChild

Cmn Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0)

```
fun clearChild(key: Any?): Unit
```

Removes the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` for the child with the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChild(kotlin.Any)` from this `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry`. If the key doesn't have an associated `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` yet (either because it hasn't been created or has already been cleared), this function does nothing.

If the store being cleared is currently retaining exited values, it will stop as a result of this call. If a child with the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChild(kotlin.Any)` is currently in the composition hierarchy, its retained values will not be persisted the next time the child content is destroyed. Children orphaned this way effectively behave as if their `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/package-summary#LocalRetainedValuesStore()` is the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ForgetfulRetainedValuesStore` until `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)` is recomposed to create a new store.

If `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#LocalRetainedValuesStoreProvider(kotlin.Any,kotlin.Function0)` is called again for the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChild(kotlin.Any)`, a new `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` will be created for the child.

| Parameters |
|---|---|
| `key: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?` | The key of the child content whose `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` should be discarded |

### clearChildren

Cmn Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0)

```
fun clearChildren(predicate: (Any?) -> Boolean): Unit
```

Bulk removes all child stores for which the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChildren(kotlin.Function1)` returns true. This function follows the same clearing rules as `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChild(kotlin.Any)`.

| Parameters |
|---|---|
| `predicate: (https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | The predicate to evaluate on all child keys in the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry`. If the predicate returns `true` for a given key, it will be cleared. If the predicate returns `false` it will remain in the collection. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry#clearChild(kotlin.Any)` |   |

### dispose

Cmn Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0)

```
fun dispose(): Unit
```

Removes all child `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore`s from this `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStoreRegistry` and marks it as ineligible for future use. This is required to invoke when the store is no longer used to retire any retained values. Failing to do so may result in memory leaks from undispatched `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetired()` and `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedEffect.composable#RetainedEffect(kotlin.Function1)` callbacks. When this function is called, all values retained in stores managed by this provider will be immediately retired.

If this store has already been disposed, this function will do nothing.