Android ViewModel & State Management

Instructions

Use ViewModel to own UI state and business logic. It should survive configuration changes and expose immutable APIs.

Kotlin 2.3+

Prefer Explicit Backing Fields instead of the traditional _state/state backing property pattern.

Kotlin 2.3: Experimental (-Xexplicit-backing-fields)

Kotlin 2.4+: Stable (recommended)

Avoid creating duplicate backing properties unless targeting older Kotlin versions.

1. UI State (StateFlow)

Purpose

Represents the persistent UI state.

Examples:

Loading
Success(data)
Error(message)
Empty

Declaration

Use an explicit backing field.

val uiState: StateFlow<UiState>
    field = MutableStateFlow(UiState.Loading)

The backing field is mutable (MutableStateFlow) while consumers only see StateFlow.

Updating State

Prefer update { } for atomic updates.

_uiState.update { old ->
    old.copy(isLoading = false)
}

With explicit backing fields:

uiState.update {
    it.copy(isLoading = false)
}

You may also assign directly when appropriate.

uiState.value = UiState.Success(data)

2. One-Off Events (SharedFlow)

Purpose

Use for transient events that should not survive recomposition or configuration changes.

Examples:

Navigate
Show Snackbar
Show Toast
Open Dialog
Request Permissions

Declaration

val uiEvent: SharedFlow<UiEvent>
    field = MutableSharedFlow(
        replay = 0,
        extraBufferCapacity = 1
    )

replay = 0 ensures events are not replayed after recreation.

Using extraBufferCapacity = 1 is recommended for UI events sent with tryEmit().

Sending Events

Suspend:

uiEvent.emit(UiEvent.NavigateBack)

Non-suspending:

uiEvent.tryEmit(UiEvent.ShowSnackbar("Saved"))

3. Collecting in Compose

StateFlow

Always collect lifecycle-aware.

val state by viewModel.uiState.collectAsStateWithLifecycle()

SharedFlow

Collect inside a single LaunchedEffect.

LaunchedEffect(Unit) {
    viewModel.uiEvent.collect { event ->
        when (event) {
            is UiEvent.NavigateBack -> { /* ... */ }
            is UiEvent.ShowSnackbar -> { /* ... */ }
        }
    }
}

Do not collect SharedFlow with collectAsState().

4. Collecting in XML/View System

Use lifecycle-aware collection.

lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.uiState.collect {
            render(it)
        }
    }
}

Likewise for events.

lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.uiEvent.collect(::handleEvent)
    }
}

5. Coroutine Scope

Launch all ViewModel work in viewModelScope.

viewModelScope.launch {
    repository.refresh()
}

Business logic should preferably be delegated to UseCases or Repositories.

6. State Design

Represent the entire screen with a single immutable state object.

data class UiState(
    val isLoading: Boolean = false,
    val items: List<Item> = emptyList(),
    val error: String? = null
)

Avoid exposing multiple unrelated StateFlows for one screen unless they truly have different lifecycles.

7. Best Practices

Expose immutable APIs (StateFlow, SharedFlow)

Prefer Explicit Backing Fields (Kotlin 2.4+)

Use immutable UI state

Use update {} when modifying state

Keep one-off events in SharedFlow

Keep business logic out of Composables

Use collectAsStateWithLifecycle()

Use repeatOnLifecycle() in Views

Launch work in viewModelScope

Do not expose MutableStateFlow

Do not use StateFlow for navigation events

Do not use SharedFlow for persistent screen state

Do not keep duplicate _state properties when Explicit Backing Fields are available

/android-viewmodel

SKILL.md