ViewModel

Artifact: androidx.lifecycle:lifecycle-viewmodel

View Source

Added in 2.0.0

Kotlin |Java

Cmn
```
abstract class ViewModel
```

Known direct subclasses

AndroidViewModel

AndroidViewModel

ViewModel that has access to the Application context.

Prepares and manages data for the UI.

ViewModels are scoped to a ViewModelStoreOwner and are retained as long as their owner is alive. This retention allows ViewModels to persist across configuration changes (e.g., Android screen rotations), making the managed data immediately available to the new owner instance.

Examples of ViewModelStoreOwners include a ComponentActivity or a Fragment.

The diagram below visualizes the relationship between the owner, store, and ViewModels:

ViewModelStoreOwner
         |
         v (owns)
  ViewModelStore <================= Retained across configuration changes
   |          |
   v          v
ViewModelA  ViewModelB
              |
              v (destroys)
         onCleared() (called when owner is permanently destroyed)

Multiple UI components can share a single ViewModel to exchange data or coordinate state. To do this, resolve the ViewModel using a shared, wider-scoped ViewModelStoreOwner (such as the parent destination in a navigation graph, a parent fragment, or the containing activity).

A ViewModel's sole responsibility is managing UI state and data. It must never hold references to a View or any Context that could cause memory leaks.

An example in Compose:

class UserViewModel : ViewModel() {
    private val _user = MutableStateFlow<User?>(null)
    val user: StateFlow<User?> = _user.asStateFlow()
}

@Composable
fun UserScreen(viewModel: UserViewModel = viewModel()) {
    val user by viewModel.user.collectAsStateWithLifecycle()
    UserContent(user)
}

See also
`ViewModelProvider`
`ViewModelStore`
`ViewModelStoreOwner`

Summary

Public constructors
`ViewModel()` Creates a new `ViewModel`.	Cmn android
`ViewModel(vararg closeables: AutoCloseable)` Creates a new `ViewModel`.	Cmn
`ViewModel(vararg closeables: AutoCloseable)` Creates a new `ViewModel`.	android
`ViewModel(viewModelScope: CoroutineScope)` Creates a new `ViewModel`.	Cmn android
`ViewModel( viewModelScope: CoroutineScope, vararg closeables: AutoCloseable )` Creates a new `ViewModel`.	Cmn
`ViewModel( viewModelScope: CoroutineScope, vararg closeables: AutoCloseable )` Creates a new `ViewModel`.	android

Public functions
`open Unit`	`addCloseable(closeable: AutoCloseable)` Adds an `AutoCloseable` resource to this `ViewModel`.	Cmn
`open Unit`	`addCloseable(closeable: AutoCloseable)` Adds an `AutoCloseable` resource to this `ViewModel`.	android
`Unit`	`addCloseable(key: String, closeable: AutoCloseable)` Adds an `AutoCloseable` resource with an associated `key` to this `ViewModel`.	Cmn
`Unit`	`addCloseable(key: String, closeable: AutoCloseable)` Adds an `AutoCloseable` resource with an associated `key` to this `ViewModel`.	android
`T?`	`<T : AutoCloseable> getCloseable(key: String)` Returns the `AutoCloseable` resource associated to the given `key`, or `null` if such a `key` is not present in this `ViewModel`.	Cmn android

Protected functions
`open Unit`	`@EmptySuper onCleared()` This method will be called when this `ViewModel` is no longer used and will be destroyed.	Cmn android

Extension properties
`CoroutineScope`	`ViewModel.viewModelScope` The `CoroutineScope` associated with this `ViewModel`.	Cmn

Public constructors

ViewModel

Cmn android

Added in 2.0.0

ViewModel()

Creates a new ViewModel.

You should never manually create a ViewModel outside of a ViewModelProvider.Factory.

ViewModel

Cmn

ViewModel(vararg closeables: AutoCloseable)

Creates a new ViewModel.

You should never manually create a ViewModel outside of a ViewModelProvider.Factory.

Parameters
`vararg closeables: AutoCloseable`	resources to be closed when the `ViewModel` is cleared, right before the `onCleared` method is called

ViewModel

android

Added in 2.8.0

ViewModel(vararg closeables: AutoCloseable)

Creates a new ViewModel.

You should never manually create a ViewModel outside of a ViewModelProvider.Factory.

Parameters
`vararg closeables: AutoCloseable`	resources to be closed when the `ViewModel` is cleared, right before the `onCleared` method is called

ViewModel

Cmn android

Added in 2.8.0

ViewModel(viewModelScope: CoroutineScope)

Creates a new ViewModel.

You should never manually create a ViewModel outside of a ViewModelProvider.Factory.

Parameters
`viewModelScope: CoroutineScope`	`CoroutineScope` to be canceled when the `ViewModel` is cleared, right before the `onCleared` method is called

ViewModel

Cmn

ViewModel(
    viewModelScope: CoroutineScope,
    vararg closeables: AutoCloseable
)

Creates a new ViewModel.

You should never manually create a ViewModel outside of a ViewModelProvider.Factory.

Parameters
`viewModelScope: CoroutineScope`	`CoroutineScope` to be canceled when the `ViewModel` is cleared, right before the `onCleared` method is called
`vararg closeables: AutoCloseable`	resources to be closed when the `ViewModel` is cleared, right before the `onCleared` method is called

ViewModel

android

Added in 2.8.0

ViewModel(
    viewModelScope: CoroutineScope,
    vararg closeables: AutoCloseable
)

Creates a new ViewModel.

You should never manually create a ViewModel outside of a ViewModelProvider.Factory.

Parameters
`viewModelScope: CoroutineScope`	`CoroutineScope` to be canceled when the `ViewModel` is cleared, right before the `onCleared` method is called
`vararg closeables: AutoCloseable`	resources to be closed when the `ViewModel` is cleared, right before the `onCleared` method is called

Public functions

addCloseable

Cmn

open fun addCloseable(closeable: AutoCloseable): Unit

Adds an AutoCloseable resource to this ViewModel. The resource will be closed right before the onCleared method is called.

If onCleared has already been called, the provided resource will not be added and will be closed immediately.

Parameters
`closeable: AutoCloseable`	resource to be closed when the `ViewModel` is cleared, right before the `onCleared` method is called

addCloseable

android

Added in 2.8.0

open fun addCloseable(closeable: AutoCloseable): Unit

Adds an AutoCloseable resource to this ViewModel. The resource will be closed right before the onCleared method is called.

If onCleared has already been called, the provided resource will not be added and will be closed immediately.

Parameters
`closeable: AutoCloseable`	resource to be closed when the `ViewModel` is cleared, right before the `onCleared` method is called

addCloseable

Cmn

fun addCloseable(key: String, closeable: AutoCloseable): Unit

Adds an AutoCloseable resource with an associated key to this ViewModel. The resource will be closed right before the onCleared method is called.

If the key already has a resource associated with it, the old resource will be replaced and closed immediately.

If onCleared has already been called, the provided resource will not be added and will be closed immediately.

Parameters
`key: String`	key to associate with the resource, for retrieval with `getCloseable`
`closeable: AutoCloseable`	resource to be closed when the `ViewModel` is cleared, right before the `onCleared` method is called

addCloseable

android

Added in 2.8.0

fun addCloseable(key: String, closeable: AutoCloseable): Unit

Adds an AutoCloseable resource with an associated key to this ViewModel. The resource will be closed right before the onCleared method is called.

If the key already has a resource associated with it, the old resource will be replaced and closed immediately.

If onCleared has already been called, the provided resource will not be added and will be closed immediately.

Parameters
`key: String`	key to associate with the resource, for retrieval with `getCloseable`
`closeable: AutoCloseable`	resource to be closed when the `ViewModel` is cleared, right before the `onCleared` method is called

getCloseable

Cmn android

fun <T : AutoCloseable> getCloseable(key: String): T?

Returns the AutoCloseable resource associated to the given key, or null if such a key is not present in this ViewModel.

Parameters
`key: String`	key associated with a resource via `addCloseable`

Protected functions

onCleared

Cmn android

Added in 2.0.0

@EmptySuper
protected open fun onCleared(): Unit

This method will be called when this ViewModel is no longer used and will be destroyed.

It is useful when the ViewModel observes data, and you need to clear the subscriptions to prevent a memory leak, as the subscriptions might hold a reference to the ViewModel even after it is no longer needed.

Clearing Sequence:

Close resources added with a key via addCloseable.
Close resources added via constructor.
Close resources added without a key via addCloseable.
Invoke the onCleared callback.

Extension properties

ViewModel.viewModelScope

Cmn

Artifact: androidx.lifecycle:lifecycle-viewmodel

View Source

Added in 2.8.0

val ViewModel.viewModelScope: CoroutineScope

The CoroutineScope associated with this ViewModel.

The CoroutineScope.coroutineContext is configured with:

SupervisorJob: ensures children jobs can fail independently of each other.
MainCoroutineDispatcher.immediate: executes jobs immediately on the main (UI) thread. If the Dispatchers.Main is not available on the current platform (e.g., Linux), we fall back to an EmptyCoroutineContext.

This scope is automatically canceled when the ViewModel is cleared, and can be replaced by using the ViewModel constructor overload that takes in a viewModelScope: CoroutineScope.

For background execution, use kotlinx.coroutines.withContext to switch to appropriate dispatchers (e.g., kotlinx.coroutines.IO).

See also
`onCleared`