# 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)

*** ** * ** ***


```
public final class SavedStateRegistry
```

<br />

*** ** * ** ***

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 |
|---|
| `public interface SavedStateRegistry.AutoRecreated` **This interface is deprecated.** \`AutoRecreated\` is deprecated. |
| `public fun interface SavedStateRegistry.SavedStateProvider` Contributes to the saved state. |
| `public fun interface SavedStateRegistry.SavedStateRestorer` Restores state for a component. |

| ### Public constructors |
|---|
| `SavedStateRegistry()` Creates an empty `SavedStateRegistry`. |
| `SavedStateRegistry(Bundle initialState)` Creates a `SavedStateRegistry` initialized with `initialState`. |

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

## Public constructors

### SavedStateRegistry

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

```
public SavedStateRegistry()
```

Creates an empty `SavedStateRegistry`.

### SavedStateRegistry

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

```
public SavedStateRegistry(Bundle initialState)
```

Creates a `SavedStateRegistry` initialized with `initialState`.

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

## Public methods

### asContainer

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

```
@MainThread
public final @NonNull SavedStateContainer asContainer()
```

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

### consumeRestoredStateForKey

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

```
@MainThread
public final SavedState consumeRestoredStateForKey(@NonNull String key)
```

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 |
|---|---|
| `@NonNull String key` | 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

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

```
@MainThread
public final @NonNull SavedStateContainer getOrCreateContainer(@NonNull String key)
```

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

| Parameters |
|---|---|
| `@NonNull String key` | identifier of the container |

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

### getSavedStateProvider

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

```
public final SavedStateRegistry.SavedStateProvider getSavedStateProvider(@NonNull String key)
```

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

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

### isRestored

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

```
@MainThread
public final boolean isRestored()
```

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

### registerSavedStateProvider

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

```
@MainThread
public final void registerSavedStateProvider(
    @NonNull String key,
    @NonNull SavedStateRegistry.SavedStateProvider provider
)
```

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 |
|---|---|
| `@NonNull String key` | The key to associate with the provider. |
| `@NonNull SavedStateRegistry.SavedStateProvider provider` | The `SavedStateProvider` to register. |

### runOnNextRecreation

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
public final void [runOnNextRecreation](https://developer.android.com/reference/androidx/savedstate/SavedStateRegistry#runOnNextRecreation(java.lang.Class))(
    @NonNull Class<@NonNull SavedStateRegistry.AutoRecreated> clazz
)
```

> [!CAUTION]
> **This method 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 |
|---|---|
| `@NonNull Class<@NonNull SavedStateRegistry.AutoRecreated> clazz` | 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

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

```
@MainThread
public final void unregisterSavedStateProvider(@NonNull String key)
```

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

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