Unsplash@davidvig

Jetpack’s ViewModel has become an essential component of modern Android development, providing a lifecycle-aware container for UI-related data that survives configuration changes. While the API appears simple on the surface, the internal machinery reveals design decisions around lifecycle management, multiplatform abstraction, resource cleanup, and thread-safe caching. Understanding how ViewModel works under the hood helps you make better architectural decisions and avoid subtle bugs.

In this article, you’ll dive deep into how Jetpack ViewModel works internally, exploring how the ViewModelStore retains instances across configuration changes, how ViewModelProvider orchestrates creation and caching, how the factory pattern enables flexible instantiation, how CreationExtras enables stateless factories, how resource cleanup is managed through the Closeable pattern, and how viewModelScope integrates coroutines with the ViewModel lifecycle.

The fundamental problem: Surviving configuration changes

Configuration changes present a fundamental challenge for Android development. When a user rotates their device, changes language settings, or triggers any configuration change, the system destroys and recreates the Activity. Any data stored in the Activity is lost:

The naive approach is to use onSaveInstanceState():

This works for small, serializable data. But what about large datasets, network connections, or objects that can’t be serialized? What about ongoing operations like network requests? The Bundle approach fails for these cases, both because of size limitations and because serialization/deserialization is expensive.

ViewModel solves this by providing a lifecycle-aware container that survives configuration changes through a retained object pattern, not serialization.

The ViewModelStore: The retention mechanism

At the heart of ViewModel’s configuration-change survival is ViewModelStore, a simple key-value store that holds ViewModel instances:

The implementation is remarkably straightforward, just a MutableMap<String, ViewModel>. The magic isn’t in the store itself, it’s in how the store is retained.

Key replacement behavior

Notice the put method’s behavior:

If a ViewModel already exists with the same key, the old ViewModel is immediately cleared. This ensures proper cleanup when a ViewModel is replaced. You might wonder when this happens, it occurs when you request a ViewModel with the same key but a different type:

This behavior is validated in the test suite:

The ViewModelStoreOwner contract

The ViewModelStoreOwner interface defines who owns the store:

This simple interface is implemented by ComponentActivity, Fragment, and NavBackStackEntry. The owner’s responsibility is twofold:

1. Retain the store across configuration changes: The store must survive Activity recreation.
2. Clear the store when truly finished: When the owner is destroyed without recreation, call ViewModelStore.clear() .

For Activities, this is typically implemented using NonConfigurationInstances, a special mechanism that allows objects to survive configuration changes. The Activity framework retains these objects during onRetainNonConfigurationInstance() and restores them in getLastNonConfigurationInstance().

Why a simple map works

You might expect a sophisticated caching mechanism, but a simple MutableMap is sufficient because:

1. Bounded size: The number of ViewModels per screen is small (typically 1–5).
2. String keys: Keys are generated from class names, making lookup O(1) with good hash distribution.
3. No eviction needed: ViewModels are cleared only when explicitly requested or when the owner is destroyed.
4. Thread safety: Access is synchronized at the ViewModelProvider level.

ViewModelProvider: The orchestration layer

ViewModelProvider is the primary API for obtaining ViewModel instances. It orchestrates the interaction between the store, factory, and creation extras:

The multiplatform abstraction

Notice the ViewModelProviderImpl delegation. The ViewModel library is a Kotlin Multiplatform library, supporting JVM, Android, iOS, and other platforms. Kotlin Multiplatform doesn’t yet support expect classes with default implementations, so the common logic is extracted to internal implementation classes:

The get-or-create pattern

The getViewModel method implements a classic get-or-create pattern:

1. Generate key: Default key is based on the class’s canonical name.
2. Check cache: Look up existing ViewModel by key.
3. Type check: Verify the cached instance is the correct type.
4. Return cached: If valid, return the cached instance.
5. Create new: If not found or wrong type, create via factory.
6. Store: Put the new instance in the store.

Thread safety with synchronized access

The synchronized(lock) block ensures thread-safe access. While ViewModel access is typically from the main thread (as indicated by @MainThread), the synchronization protects against edge cases where background threads might access ViewModels, particularly in testing scenarios or when using viewModelScope.

The OnRequeryFactory callback

The OnRequeryFactory is a special mechanism for factories that need to perform actions when a cached ViewModel is retrieved:

This is used internally by SavedStateHandle to reconnect the ViewModel with the current SavedStateRegistry after configuration changes. When a ViewModel is retrieved from cache, the factory’s onRequery method is called, allowing it to update references that might have changed.

Key generation from class names

The default key generation prevents accidental conflicts:

The prefix "androidx.lifecycle.ViewModelProvider.DefaultKey:" ensures keys don’t collide with custom keys users might provide. The canonical name requirement also explains why local and anonymous classes can’t be ViewModels, they don’t have canonical names:

The Factory pattern: Flexible instantiation

ViewModelProvider.Factory is the mechanism for creating ViewModel instances:

The method overload chain

The factory interface has three create method variants, forming a chain:

1. create(KClass<T>, CreationExtras): The Kotlin-first API, delegates to Java variant
2. create(Class<T>, CreationExtras): The primary implementation point, defaults to no-extras variant
3. create(Class<T>): Legacy API, throws by default

This chain allows backwards compatibility while encouraging the modern CreationExtras-based approach.

NewInstanceFactory: Reflection-based creation

The simplest factory uses reflection to create ViewModels with no-arg constructors:

The JVM implementation uses reflection with careful error handling:

The public modifier check is important for test consistency. In instrumentation tests, R8 may strip access modifiers, making private constructors accessible. JVM tests enforce access restrictions strictly. This explicit check ensures consistent behavior across test environments.

AndroidViewModelFactory: Application-aware creation

AndroidViewModelFactory extends NewInstanceFactory to support AndroidViewModel, which requires an Application parameter. This factory maintains backwards compatibility while embracing the modern CreationExtras approach:

The factory implements a cascading resolution strategy: first checking if an Application was passed to the constructor (legacy approach), then looking in CreationExtras via APPLICATION_KEY (modern stateless approach), and finally falling back to NewInstanceFactory for regular ViewModels or throwing if an AndroidViewModel has no Application available.

The unused: Int parameter in the private constructor is a clever trick to differentiate between overloaded constructors, since the compiler couldn’t otherwise distinguish constructor() from constructor(application: Application?) when called with null.

The instantiation uses reflection (modelClass.getConstructor(Application::class.java).newInstance(app)), which means your AndroidViewModel subclass must have a constructor accepting exactly one Application parameter. For additional dependencies, you’ll need a custom factory or dependency injection frameworks like Hilt.

InitializerViewModelFactory: Lambda-based creation

For ViewModels with custom dependencies, InitializerViewModelFactory provides a DSL-based approach that reduces boilerplate:

The DSL is powered by a builder class that collects initializer lambdas, where each initializer pairs a KClass with its creation lambda:

The @ViewModelFactoryDsl annotation is a DSL marker that prevents nested builder scopes from accidentally accessing outer scope methods. The initializer lambda receives CreationExtras as its receiver, allowing direct access to extras via get().

At creation time, the factory performs a linear search through initializers to find a matching class:

The linear search is acceptable because the number of ViewModels per factory is typically small (1–5) and ViewModel creation happens infrequently (once per lifecycle).

CreationExtras: Stateless factory configuration

CreationExtras is a type-safe, key-value container for passing configuration to factories without making them stateful. Instead of factories holding dependencies via constructor injection, dependencies are passed at creation time:

Type-safe keys

Each key is parameterized by the value type it’s associated with, providing compile-time type safety. When you retrieve a value with extras[APPLICATION_KEY], the return type is automatically Application?:

The key creation uses an inline function that creates a new anonymous object implementing the Key interface. Since each key is a unique object instance, keys are compared by identity (===), ensuring no accidental collisions even if two keys have the same type parameter:

MutableCreationExtras for modification

The base CreationExtras class is read-only, while MutableCreationExtras allows adding entries. This separation follows Kotlin’s collection design philosophy (like List vs MutableList), preventing factories from accidentally modifying shared extras:

Integration with ViewModelProvider

The ViewModelProvider automatically adds the ViewModel’s key to extras before calling the factory, which is essential for features like SavedStateHandle that need the key to scope persistence correctly:

HasDefaultViewModelProviderFactory

ViewModelStoreOwner implementations can provide default factory and extras through the HasDefaultViewModelProviderFactory interface. ComponentActivity and Fragment both implement this, providing factories that support SavedStateHandle with APPLICATION_KEY pre-populated:

ComponentActivity and Fragment both implement this interface, providing factories that support SavedStateHandle and proper CreationExtras with APPLICATION_KEY pre-populated.

When creating a ViewModelProvider from a ViewModelStoreOwner, these defaults are automatically used:

This pattern enables progressive enhancement: simple ViewModels work with default factories, while complex ViewModels can receive rich configuration through extras without changing how you obtain the ViewModelProvider.

The ViewModel class: Resource management

The ViewModel class manages resource lifecycle through the AutoCloseable pattern. The expect keyword indicates this is a Kotlin Multiplatform declaration, where each platform provides its own actual implementation:

The ViewModelImpl internal implementation

The actual implementation is delegated to ViewModelImpl, following the multiplatform pattern where common logic is extracted to internal classes. The @Volatile annotation on isCleared ensures visibility across threads, which is crucial for the post-clear protection mechanism:

Two-tier closeable storage

The implementation maintains two collections: keyToCloseables for resources that need retrieval after registration (like viewModelScope), and closeables for fire-and-forget cleanup. Using a Set for anonymous closeables prevents duplicate registration from causing double-closing.

The clearing sequence

When a ViewModel is cleared, resources are cleaned up in a specific order. The isCleared = true flag is set before the synchronized block to prevent concurrent addCloseable calls from adding resources that would be missed:

The anonymous closeables set is cleared, but keyToCloseables is intentionally kept. This prevents accidental recreation of resources like viewModelScope if code accesses it after clearing.

Post-clear protection

Adding closeables after clearing immediately closes them, preventing resource leaks in edge cases where coroutines are still running when the ViewModel is cleared:

Also, notice that when adding a keyed closeable, any existing closeable with the same key is automatically closed, enabling replacement patterns.

Nullable impl for mocking

The JVM implementation has a nullable impl to support mocking frameworks. When you mock a ViewModel, the mock doesn’t call the real constructor, so impl is never initialized. Without the nullable type and safe call (impl?.clear()), tests would crash with NullPointerException:

viewModelScope: Coroutine integration

The viewModelScope extension property provides a lifecycle-aware CoroutineScope that’s automatically cancelled when the ViewModel is cleared:

Lazy creation with keyed storage

The scope is created lazily on first access and stored using the keyed closeable mechanism. The key is intentionally verbose to avoid collisions with user-defined keys:

CloseableCoroutineScope

The bridge between coroutines and the closeable system is CloseableCoroutineScope, which implements both CoroutineScope and AutoCloseable. When close() is called during ViewModel clearing, all running coroutines are cancelled:

Platform-aware dispatcher selection

As a Kotlin Multiplatform library, ViewModel works on platforms without a main thread concept by falling back to EmptyCoroutineContext. Notice the use of Dispatchers.Main.immediate rather than Dispatchers.Main, which avoids unnecessary redispatching when already on the main thread:

SupervisorJob for independent child failure

The scope uses SupervisorJob() which allows child coroutines to fail independently. With a regular Job, if one child fails it cancels all siblings. This design matches UI application expectations where a failing network request shouldn’t cancel an ongoing database operation.

ViewModelLazy: Kotlin property delegation

The viewModels() delegate uses ViewModelLazy:

Double-caching architecture

The lazy delegate caches the ViewModel reference locally after first access. This is a double-caching pattern:

1. ViewModelStore cache: The canonical cache that survives configuration changes.
2. ViewModelLazy cache: A local cache to avoid repeated ViewModelProvider creation.

The local cache is an optimization, creating a ViewModelProvider and looking up the ViewModel is cheap, but caching avoids even that minimal overhead on subsequent accesses.

Lambda producers for deferred access

All three producers (store, factory, extras) are lambdas, allowing deferred evaluation:

This is particularly important for fragments where the Activity might not be available during property initialization.

Android-specific: AGP desugaring compatibility

Android has a special compatibility layer for handling AGP (Android Gradle Plugin) desugaring issues that arise when mixing libraries compiled against different ViewModel versions:

This cascade of try-catch blocks handles cases where factories compiled with older ViewModel versions lack newer create method variants. The AbstractMethodError occurs when the runtime calls a method that doesn’t exist in the compiled bytecode, typically when an old factory only has create(Class<T>) but the runtime expects create(Class<T>, CreationExtras). The defensive cascade gracefully degrades through method variants, ensuring ViewModel creation works regardless of library version mismatches.

Performance characteristics and design trade-offs

The ViewModel system makes several deliberate design trade-offs that balance correctness, flexibility, and performance.

Synchronization overhead

Both ViewModelProviderImpl and ViewModelImpl use synchronized blocks for thread-safe access:

This adds minimal overhead since ViewModel access typically happens on the main thread, the critical sections are short (simple map operations), and lock contention is rare. The design prioritizes correctness over micro-optimization, since a rare race condition would be far more costly than the imperceptible synchronization overhead.

Reflection cost

NewInstanceFactory uses Java reflection to dynamically instantiate ViewModel classes:

Reflection is slower than direct constructor calls due to runtime type checking and dynamic method resolution. However, this cost is negligible because ViewModels are created infrequently (once per lifecycle), and the flexibility of instantiating any ViewModel subclass without compile-time knowledge far outweighs the minor overhead.

Map-based storage

Using MutableMap for ViewModelStore provides O(1) lookup but O(n) clear since each ViewModel must be individually cleared:

Since ViewModelStores typically hold only 1–5 ViewModels, the linear-time clear has no practical impact. The simplicity of using a standard HashMap makes the code easier to understand and maintain, providing more value than theoretical optimizations for this bounded use case.

Nullable impl for mockability

The nullable impl in JVM ViewModel adds a null check on every operation:

This microscopic overhead enables proper mocking behavior. When mocking frameworks create ViewModel mocks, they bypass the real constructor, leaving impl uninitialized. The nullable type prevents NullPointerException in tests, a worthwhile trade-off.

Real-world patterns: Understanding ViewModel usage

Understanding the internals helps you recognize patterns and anti-patterns in real-world usage.

Pattern 1: Scoped ViewModel sharing

ViewModels can be shared across fragments by using the Activity’s ViewModelStore instead of each Fragment’s own store:

Both fragments get the same ViewModel instance because they use the same ViewModelStore (the Activity’s). This enables sibling fragment communication through shared state. The internal mechanism:

Pattern 2: Custom keys for multiple instances

You can have multiple instances of the same ViewModel class by providing custom keys:

The key includes the custom string, creating separate cache entries in the ViewModelStore. This is useful for scenarios like managing multiple user profiles or chat conversations simultaneously.

Pattern 3: Factory injection with CreationExtras

Modern factories are stateless, receiving all dependencies via CreationExtras at creation time:

This allows the factory to be a singleton while the configuration varies per-call, avoiding the need to create a new factory instance for each ViewModel with different dependencies.

Anti-pattern: Accessing Context in ViewModel

The first approach can leak the Activity because the ViewModel survives configuration changes while holding a reference to the destroyed Activity. Use AndroidViewModel for Application context, or pass Context to individual methods when needed.

Anti-pattern: Blocking in onCleared

Did you know that onCleared() is called on the main thread? Blocking operations like network shutdown or database cleanup should be offloaded to background threads using addCloseable with coroutines:

This article was previously published on proandroiddev.com