ViewModelProvider

Artifact: androidx.lifecycle:lifecycle-viewmodel

View Source

Added in 2.0.0

---

Kotlin |Java

public final class ViewModelProvider

---

A utility class that manages the lifecycle, caching, and instantiation of ViewModel instances.

A ViewModelProvider acts as the central orchestrator that coordinates:

1. Caching / Retrieval: It checks a ViewModelStore to see if an instance of the requested ViewModel class already exists under a given key. If found, it returns the cached instance.

2. Extras Injection: It automatically populates a MutableCreationExtras with the unique registration key under VIEW_MODEL_KEY, combining it with default CreationExtras provided by the owner.

3. Instantiation: If no cached instance exists, it invokes a ViewModelProvider.Factory to create a new instance using the prepared extras, caches it in the ViewModelStore, and returns it.

To ensure that ViewModel instances survive configuration changes, the underlying ViewModelStore must be retained (for example, by using a ViewModelStoreOwner such as ComponentActivity or Fragment which automatically handles this retention).

The following diagram illustrates the retrieval and creation flow of a ViewModel instance:

        ViewModelProvider.get(key)
                    |
                    v
           Is ViewModel cached
           in ViewModelStore?
                 /   \
               Yes    No
               /       \
              v         v
    Return cached      Create via Factory & CreationExtras,
    ViewModel          cache in ViewModelStore, and return

See also
CreationExtras
ViewModel
ViewModelProvider.Factory
ViewModelStore
ViewModelStoreOwner

Summary

Nested types
public class ViewModelProvider.AndroidViewModelFactory extends ViewModelProvider.NewInstanceFactory Factory that creates AndroidViewModel and ViewModel instances.
public static class ViewModelProvider.Companion
public interface ViewModelProvider.Factory Implementations of the Factory interface are responsible for instantiating ViewModels.
public class ViewModelProvider.NewInstanceFactory implements ViewModelProvider.Factory Factory that creates ViewModel instances by calling their no-argument constructor.
public class ViewModelProvider.NewInstanceFactory implements ViewModelProvider.Factory Simple factory, which calls empty constructor on the give class.
public static class ViewModelProvider.NewInstanceFactory.Companion

Public constructors
ViewModelProvider(@NonNull ViewModelStoreOwner owner) Creates ViewModelProvider.
ViewModelProvider(     @NonNull ViewModelStoreOwner owner,     @NonNull ViewModelProvider.Factory factory ) Creates a ViewModelProvider.
ViewModelProvider(     @NonNull ViewModelStore store,     @NonNull ViewModelProvider.Factory factory,     @NonNull CreationExtras defaultCreationExtras ) Creates a ViewModelProvider.

Public methods
@NonNull T	<T extends ViewModel> get(@NonNull Class<@NonNull T> modelClass) Returns an existing ViewModel or creates a new one in the scope (usually, a Fragment or an Activity) associated with this ViewModelProvider.
@NonNull T	<T extends ViewModel> get(@NonNull String key, @NonNull Class<@NonNull T> modelClass) Returns an existing ViewModel or creates a new one in the scope (usually, a Fragment or an Activity) associated with this ViewModelProvider.

Extension functions
final @NonNull VM	@MainThread <VM extends ViewModel> ViewModelProviderGetKt.get(     @NonNull ViewModelProvider receiver ) Returns an existing ViewModel or creates a new one in the scope (usually, a fragment or an activity), associated with this ViewModelProvider.
final @NonNull VM	@MainThread <VM extends ViewModel> ViewModelProviderGetKt.get(     @NonNull ViewModelProvider receiver,     @NonNull String key ) Returns an existing ViewModel or creates a new one in the scope (usually, a fragment or an activity), associated with this ViewModelProvider and the given key.

Public constructors

ViewModelProvider

Added in 2.2.0

public ViewModelProvider(@NonNull ViewModelStoreOwner owner)

Creates ViewModelProvider. This will create ViewModel instances and retain them in the ViewModelStore of the given ViewModelStoreOwner.

This method will use the default factory if the owner implements HasDefaultViewModelProviderFactory. Otherwise, a NewInstanceFactory will be used.

ViewModelProvider

Added in 2.0.0

public ViewModelProvider(
    @NonNull ViewModelStoreOwner owner,
    @NonNull ViewModelProvider.Factory factory
)

Creates a ViewModelProvider. This provider generates ViewModel instances using the specified Factory and stores them within the ViewModelStore of the provided ViewModelStoreOwner.

Parameters
@NonNull ViewModelStoreOwner owner	ViewModelStoreOwner that will manage the lifecycle of the created ViewModel instances
@NonNull ViewModelProvider.Factory factory	Factory responsible for creating new ViewModel instances

ViewModelProvider

Added in 2.5.0

public ViewModelProvider(
    @NonNull ViewModelStore store,
    @NonNull ViewModelProvider.Factory factory,
    @NonNull CreationExtras defaultCreationExtras
)

Creates a ViewModelProvider. This provider generates ViewModel instances using the specified Factory and stores them within the ViewModelStore of the provided ViewModelStoreOwner.

Parameters
@NonNull ViewModelStore store	ViewModelStore where ViewModels will be stored
@NonNull ViewModelProvider.Factory factory	Factory responsible for creating new ViewModel instances
@NonNull CreationExtras defaultCreationExtras	additional data to be passed to the Factory during ViewModel creation

Public methods

get

Added in 2.0.0

public @NonNull T <T extends ViewModel> get(@NonNull Class<@NonNull T> modelClass)

Returns an existing ViewModel or creates a new one in the scope (usually, a Fragment or an Activity) associated with this ViewModelProvider.

The created ViewModel is associated with the given scope and will be retained as long as the scope is alive (e.g., if it is an Activity, until it is finished or the process is killed).

Parameters
@NonNull Class<@NonNull T> modelClass	Class of the ViewModel to retrieve or create

Returns
@NonNull T	ViewModel instance of type T

Throws
IllegalArgumentException	if the given modelClass is a local or anonymous class

get

Added in 2.0.0

public @NonNull T <T extends ViewModel> get(@NonNull String key, @NonNull Class<@NonNull T> modelClass)

Returns an existing ViewModel or creates a new one in the scope (usually, a Fragment or an Activity) associated with this ViewModelProvider.

The created ViewModel is associated with the given scope and will be retained as long as the scope is alive (e.g., if it is an Activity, until it is finished or the process is killed).

Parameters
@NonNull String key	identifier of the ViewModel
@NonNull Class<@NonNull T> modelClass	Class of the ViewModel to retrieve or create

Returns
@NonNull T	ViewModel instance of type T

Extension functions

ViewModelProviderGetKt.get

Artifact: androidx.lifecycle:lifecycle-viewmodel

View Source

@MainThread
public final @NonNull VM <VM extends ViewModel> ViewModelProviderGetKt.get(
    @NonNull ViewModelProvider receiver
)

Returns an existing ViewModel or creates a new one in the scope (usually, a fragment or an activity), associated with this ViewModelProvider.

See also
get	(Class)

ViewModelProviderGetKt.get

Artifact: androidx.lifecycle:lifecycle-viewmodel

View Source

@MainThread
public final @NonNull VM <VM extends ViewModel> ViewModelProviderGetKt.get(
    @NonNull ViewModelProvider receiver,
    @NonNull String key
)

Returns an existing ViewModel or creates a new one in the scope (usually, a fragment or an activity), associated with this ViewModelProvider and the given key.

Parameters
@NonNull String key	The key to use to identify the ViewModel.

See also
get	(String, Class)