public final class ViewModelStoreProvider

Manages a set of ViewModelStore instances scoped to a parent ViewModelStore.

This class allows the creation of "child" scopes that survive configuration changes (via the parent) but can be independently cleared when no longer needed.

Important: This class prevents a child ViewModel from being cleared while they are still in use (e.g., during exit animations). Consumers must call acquireToken to mark a child ViewModelStore as active and then call ReferenceToken.close to release the token when finished. Calling clearKey or clearAllKeys will only perform the actual cleanup once all of a store's tokens have been released.

Null parentStore: If parentStore is EXPLICITLY null, this creates a root provider that runs independently. It manages its own state and will not be automatically cleared by configuration changes; you must manually call clearAllKeys to clean it up.

Summary

Nested types

Represents an active hold on a specific ViewModelStore.

Public constructors
ViewModelStoreProvider(
    ViewModelStoreOwner parentOwner,
    Object parentKey,
    @NonNull SavedState defaultArgs,
    @NonNull CreationExtras defaultCreationExtras,
    @NonNull ViewModelProvider.Factory defaultFactory
)

Constructs a ViewModelStoreProvider bound to a parent ViewModelStoreOwner.
ViewModelStoreProvider(
    ViewModelStore parentStore,
    Object parentKey,
    @NonNull SavedState defaultArgs,
    @NonNull CreationExtras defaultCreationExtras,
    @NonNull ViewModelProvider.Factory defaultFactory
)

Public methods
final @NonNull ViewModelStoreProvider.ReferenceToken

Increments the reference count for the ViewModelStore associated with the given key, ensuring it is not cleared until the returned ReferenceToken is released.
final void

Triggers a cleanup pass on all managed stores.
final void

Marks the ViewModelStore associated with the given key as removable.
final @NonNull ViewModelStore

Retrieves or creates a ViewModelStore associated with the given key.
final @NonNull ViewModelStoreOwner
getOrCreateOwner(
    Object key,
    SavedStateRegistryOwner savedStateRegistryOwner,
    @NonNull SavedState defaultArgs,
    @NonNull CreationExtras defaultCreationExtras,
    @NonNull ViewModelProvider.Factory defaultFactory
)

Retrieves or creates a ViewModelStoreOwner associated with the given key.

Public constructors

ViewModelStoreProvider

public ViewModelStoreProvider(
    ViewModelStoreOwner parentOwner,
    Object parentKey,
    @NonNull SavedState defaultArgs,
    @NonNull CreationExtras defaultCreationExtras,
    @NonNull ViewModelProvider.Factory defaultFactory
)

Constructs a ViewModelStoreProvider bound to a parent ViewModelStoreOwner.

Parameters
ViewModelStoreOwner parentOwner

The parent ViewModelStoreOwner to bind to, or null for an independent root provider.
Object parentKey

A unique identifier used to scope this provider and its underlying state within the parentOwner. Providers sharing the same key will share the same internal state. A null key is valid and acts as its own distinct shared scope. Defaults to null.
@NonNull SavedState defaultArgs

The default SavedState arguments to use for child stores. These arguments are merged with any default arguments in defaultCreationExtras. If the same key exists in both, the value from defaultArgs takes precedence.
@NonNull CreationExtras defaultCreationExtras

The default creation extras to use for child stores. Defaults to resolving from the parentOwner.
@NonNull ViewModelProvider.Factory defaultFactory

The default factory to use for child stores. Defaults to resolving from the parentOwner.

ViewModelStoreProvider

public ViewModelStoreProvider(
    ViewModelStore parentStore,
    Object parentKey,
    @NonNull SavedState defaultArgs,
    @NonNull CreationExtras defaultCreationExtras,
    @NonNull ViewModelProvider.Factory defaultFactory
)
Parameters
ViewModelStore parentStore

The parent ViewModelStore to bind to, or null for an independent root provider.
Object parentKey

A unique identifier used to scope this provider and its underlying state within the parentStore. Providers sharing the same key will share the same internal state. A null key is valid and acts as its own distinct shared scope. Defaults to null.
@NonNull SavedState defaultArgs

The default SavedState arguments to use for child stores. These arguments are merged with any default arguments in defaultCreationExtras. If the same key exists in both, the value from defaultArgs takes precedence.
@NonNull CreationExtras defaultCreationExtras

The default creation extras to use for child stores.
@NonNull ViewModelProvider.Factory defaultFactory

The default factory to use for child stores.

Public methods

acquireToken

public final @NonNull ViewModelStoreProvider.ReferenceToken acquireToken(Object key)

Increments the reference count for the ViewModelStore associated with the given key, ensuring it is not cleared until the returned ReferenceToken is released.

Parameters
Object key

The unique identifier for the child scope. A null key is valid and is treated as a distinct scope.
Returns
@NonNull ViewModelStoreProvider.ReferenceToken

A token that must be released via ReferenceToken.close when the caller no longer requires the store.

clearAllKeys

public final void clearAllKeys()

Triggers a cleanup pass on all managed stores.

Any ViewModelStore that has a reference count of zero will have its ViewModelStore.clear method called and will be removed from the internal map. Stores with active references are marked as removable and will be deferred until their count reaches zero.

clearKey

public final void clearKey(Object key)

Marks the ViewModelStore associated with the given key as removable.

If the store currently has a reference count of zero, it is cleared immediately. Otherwise, the actual cleanup is deferred until all acquired tokens are released.

Parameters
Object key

The unique identifier for the child scope. Passing null will target the specific scope associated with the null key.

getOrCreate

public final @NonNull ViewModelStore getOrCreate(Object key)

Retrieves or creates a ViewModelStore associated with the given key.

If a store with this key already exists, it is returned. If not, a new store is created. To protect this store from being prematurely cleared, you must call acquireToken.

Parameters
Object key

The unique identifier for the child scope. A null key is valid and is treated as a distinct scope.
Returns
@NonNull ViewModelStore

The ViewModelStore tied to the provided key.

getOrCreateOwner

public final @NonNull ViewModelStoreOwner getOrCreateOwner(
    Object key,
    SavedStateRegistryOwner savedStateRegistryOwner,
    @NonNull SavedState defaultArgs,
    @NonNull CreationExtras defaultCreationExtras,
    @NonNull ViewModelProvider.Factory defaultFactory
)

Retrieves or creates a ViewModelStoreOwner associated with the given key.

This method creates a new lightweight wrapper around the ViewModelStore.

Important: This does not automatically increment the reference count. If you are holding onto this owner asynchronously or across recompositions, you should call acquireToken to protect its lifecycle.

Saved State Support: If a savedStateRegistryOwner is provided, the returned ViewModelStoreOwner will also implement SavedStateRegistryOwner, delegating state resolution to the provided owner. This is required if ViewModels within this scope depend on SavedStateHandle. When saved state is enabled and defaultFactory is not explicitly overridden, it automatically upgrades to a SavedStateViewModelFactory.

Parameters
Object key

The unique identifier for the child scope. A null key is valid and is treated as a distinct scope.
SavedStateRegistryOwner savedStateRegistryOwner

An optional parent registry owner to delegate saved state operations to. If null, the returned owner will not support SavedStateHandle.
@NonNull SavedState defaultArgs

The default SavedState arguments to use for child stores. These arguments are merged with any default arguments in defaultCreationExtras. If the same key exists in both, the value from defaultArgs takes precedence.
@NonNull CreationExtras defaultCreationExtras

An optional override for the default CreationExtras.
@NonNull ViewModelProvider.Factory defaultFactory

An optional override for the default ViewModelProvider.Factory.
Returns
@NonNull ViewModelStoreOwner

A scoped ViewModelStoreOwner, which optionally supports saved state.
Throws
IllegalArgumentException

If savedStateRegistryOwner is provided but its lifecycle is past the INITIALIZED or CREATED state.