# SavedStateRegistry

Artifact: [androidx.savedstate:savedstate](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt) [View Source](https://cs.android.com/search?q=file:androidx/savedstate/SavedStateRegistry.+class:androidx.savedstate.SavedStateRegistry) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.0.0)

*** ** * ** ***

Common/AllAndroid/JVM
- Cmn

  ```
  class SavedStateRegistry
  ```

*** ** * ** ***

Registry for components that consume and contribute to saved state.

Use this registry to save and restore component state across process death or recreation.

## Summary

| ### Nested types |
|---|
| `interface SavedStateRegistry.AutoRecreated` **This interface is deprecated.** \`AutoRecreated\` is deprecated. |
| `fun interface SavedStateRegistry.SavedStateProvider` Contributes to the saved state. |
| `fun interface SavedStateRegistry.SavedStateRestorer` Restores state for a component. |

| ### Public constructors |
|---|---|
| `SavedStateRegistry()` Creates an empty `SavedStateRegistry`. | Cmn android |
| `SavedStateRegistry(initialState: Bundle?)` Creates a `SavedStateRegistry` initialized with `initialState`. | android |
| `SavedStateRegistry(initialState: SavedState?)` Creates a `SavedStateRegistry` initialized with `initialState`. | Cmn |

| ### Public functions |
|---|---|---|
| `SavedStateContainer` | `@MainThread asContainer()` Returns the underlying `SavedStateContainer` managing this `SavedStateRegistry`. | Cmn android |
| `SavedState?` | `@MainThread consumeRestoredStateForKey(key: String)` Consumes the saved state previously supplied by a `SavedStateProvider` registered with the given `key`. | Cmn android |
| `SavedStateContainer` | `@MainThread getOrCreateContainer(key: String)` Retrieves an existing nested `SavedStateContainer` associated with `key`, or creates and registers a new child `SavedStateContainer` if none exists. | Cmn android |
| `SavedStateRegistry.SavedStateProvider?` | `getSavedStateProvider(key: String)` Returns the `SavedStateProvider` previously registered with `registerSavedStateProvider`, or `null` if no provider has been registered with the given `key`. | Cmn android |
| `Unit` | `@MainThread registerSavedStateProvider( key: String, provider: SavedStateRegistry.SavedStateProvider )` Registers a `SavedStateProvider` with the given `key`. | Cmn android |
| `Unit` | `@MainThread [runOnNextRecreation](https://developer.android.com/reference/kotlin/androidx/savedstate/SavedStateRegistry#runOnNextRecreation(java.lang.Class))(clazz: Class<SavedStateRegistry.AutoRecreated>)` **This function is deprecated.** \`runOnNextRecreation\` is deprecated. | android |
| `Unit` | `@MainThread unregisterSavedStateProvider(key: String)` Unregisters a component previously registered with the given `key`. | Cmn android |

| ### Public properties |
|---|---|---|
| `Boolean` | `isRestored` Returns `true` if state has been restored and can be safely consumed with `consumeRestoredStateForKey`, `false` otherwise. | Cmn android |

## Public constructors

### SavedStateRegistry

Cmn android Added in [1.6.0-alpha05](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.6.0-alpha05)

```
SavedStateRegistry()
```

Creates an empty `SavedStateRegistry`.

### SavedStateRegistry

android Added in [1.6.0-alpha05](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.6.0-alpha05)

```
SavedStateRegistry(initialState: Bundle?)
```

Creates a `SavedStateRegistry` initialized with `initialState`.

| Parameters |
|---|---|
| `initialState: Bundle?` | The initial saved state to restore from. |

### SavedStateRegistry

Cmn

```
SavedStateRegistry(initialState: SavedState?)
```

Creates a `SavedStateRegistry` initialized with `initialState`.

| Parameters |
|---|---|
| `initialState: SavedState?` | The initial saved state to restore from. |

## Public functions

### asContainer

Cmn android Added in [1.6.0-alpha05](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.6.0-alpha05)

```
@MainThread
fun asContainer(): SavedStateContainer
```

Returns the underlying `SavedStateContainer` managing this `SavedStateRegistry`.

### consumeRestoredStateForKey

Cmn android Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.0.0)

```
@MainThread
fun consumeRestoredStateForKey(key: String): SavedState?
```

Consumes the saved state previously supplied by a `SavedStateProvider` registered with the given `key`.

If the registered `SavedStateProvider` implements `SavedStateRestorer`, the state is restored automatically during restoration, and calls to this method with the same key return `null`.

This call clears the internal reference to the returned saved state. Subsequent calls with the same key return `null`.

All unconsumed values are preserved during state saving.

| Parameters |
|---|---|
| `key: String` | The key with which the `SavedStateProvider` was previously registered. |

| Returns |
|---|---|
| `SavedState?` | The previously saved state, or `null` if none exists or it has already been consumed. |

### getOrCreateContainer

Cmn android Added in [1.6.0-alpha05](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.6.0-alpha05)

```
@MainThread
fun getOrCreateContainer(key: String): SavedStateContainer
```

Retrieves an existing nested `SavedStateContainer` associated with `key`, or creates and registers a new child `SavedStateContainer` if none exists.

| Parameters |
|---|---|
| `key: String` | identifier of the container |

| Returns |
|---|---|
| `SavedStateContainer` | existing or newly created child `SavedStateContainer` instance |

### getSavedStateProvider

Cmn android Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.2.0)

```
fun getSavedStateProvider(key: String): SavedStateRegistry.SavedStateProvider?
```

Returns the `SavedStateProvider` previously registered with `registerSavedStateProvider`, or `null` if no provider has been registered with the given `key`.

| Parameters |
|---|---|
| `key: String` | The key used to register the `SavedStateProvider`. |

### registerSavedStateProvider

Cmn android Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.0.0)

```
@MainThread
fun registerSavedStateProvider(
    key: String,
    provider: SavedStateRegistry.SavedStateProvider
): Unit
```

Registers a `SavedStateProvider` with the given `key`.

This `SavedStateProvider` will be called during state saving. The returned state is associated with the given `key` and can be consumed after restoration via `consumeRestoredStateForKey`.

If the registered `provider` implements `SavedStateRestorer`, its `SavedStateRestorer.restoreState` method is automatically invoked during state restoration, or immediately if state has already been restored.

If a provider was already registered with the given `key`, it is replaced with the new `provider`.

| Parameters |
|---|---|
| `key: String` | The key to associate with the provider. |
| `provider: SavedStateRegistry.SavedStateProvider` | The `SavedStateProvider` to register. |

### runOnNextRecreation

android Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.0.0) Deprecated in [1.6.0-alpha05](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.6.0-alpha05)

```
@MainThread
fun [runOnNextRecreation](https://developer.android.com/reference/kotlin/androidx/savedstate/SavedStateRegistry#runOnNextRecreation(java.lang.Class))(clazz: Class<SavedStateRegistry.AutoRecreated>): Unit
```

> [!CAUTION]
> **This function is deprecated.**   
> \`runOnNextRecreation\` is deprecated. Use \`SavedStateProvider\` and \`SavedStateConsumer\` to save and restore state.

Executes the given class when the owning component restarted.

The given class will be automatically instantiated via default constructor and method `AutoRecreated.onRecreated` will be called. It is called as part of dispatching of `androidx.lifecycle.Lifecycle.Event.ON_CREATE` event.

| Parameters |
|---|---|
| `clazz: Class<SavedStateRegistry.AutoRecreated>` | that will need to be instantiated on the next component recreation |

| Throws |
|---|---|
| `IllegalArgumentException` | if you try to call if after `Lifecycle.Event.ON_STOP` was dispatched |

### unregisterSavedStateProvider

Cmn android Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.0.0)

```
@MainThread
fun unregisterSavedStateProvider(key: String): Unit
```

Unregisters a component previously registered with the given `key`.

| Parameters |
|---|---|
| `key: String` | The key with which the component was previously registered. |

## Public properties

### isRestored

Cmn android Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/savedstate.md.txt#1.0.0)

```
val isRestored: Boolean
```

Returns `true` if state has been restored and can be safely consumed with `consumeRestoredStateForKey`, `false` otherwise.