MVI Editor

Overview

MVI (Model-View-Intent) is a unidirectional data flow pattern for Android UIs:

User Action → Event → ViewModel → State / SideEffect → UI

This skill is fully self-contained. Everything you need is defined here — no external MVI library required. Copy the foundation once and reuse it across all features.

Data Flow

┌──────────────────────────────────────────────────┐
│                    UI Layer                      │
│                                                  │
│   ┌──────────┐  events   ┌─────────────────┐    │
│   │  Screen  │ ────────► │   ViewModel     │    │
│   │          │           │                 │    │
│   │          │ ◄──────── │  _state         │    │
│   │          │  state    │  _sideEffects   │    │
│   └──────────┘           └─────────────────┘    │
│         │                        │               │
│   side effects            domain calls           │
│         ▼                        ▼               │
│   Navigation /            Use Cases /            │
│   Toast / Dialog          Repositories           │
└──────────────────────────────────────────────────┘

Step 1 — Foundation (copy once per project)

Create this base class in a shared module. It encapsulates the boilerplate that every ViewModel would otherwise duplicate:

// shared/mvi/MviViewModel.kt

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.receiveAsFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch

/**
 * Base ViewModel for the MVI pattern.
 *
 * S — State:      immutable data class representing what the UI renders
 * E — Event:      sealed interface for user actions / UI triggers
 * F — SideEffect: sealed interface for one-time effects (navigation, toasts…)
 */
abstract class MviViewModel<S : Any, E : Any, F : Any>(
    initialState: S,
) : ViewModel() {

    private val _state = MutableStateFlow(initialState)
    val state: StateFlow<S> = _state.asStateFlow()

    private val _sideEffects = Channel<F>(Channel.BUFFERED)
    val sideEffects: Flow<F> = _sideEffects.receiveAsFlow()

    /** Single entry point for all UI events. */
    abstract fun onEvent(event: E)

    /** Update state using a reducer. Thread-safe via MutableStateFlow.update. */
    protected fun updateState(reducer: S.() -> S) {
        _state.update { it.reducer() }
    }

    /** Emit a one-time side effect. */
    protected fun emitEffect(effect: F) {
        viewModelScope.launch { _sideEffects.send(effect) }
    }
}

No base class preferred? Skip MviViewModel and copy the _state + _sideEffects boilerplate directly into each ViewModel — see the "Without base class" example below.

Step 2 — Contract (one file per feature)

Three plain Kotlin types — no external interfaces to extend:

// feature/orders/OrderContract.kt

/** Snapshot of what the UI should render. All fields have defaults. */
data class OrderViewState(
    val isLoading: Boolean = false,
    val orders: List<Order> = emptyList(),
    val errorMessage: String? = null,
)

/** User actions and UI triggers. */
sealed interface OrderEvent {
    data object OnScreenOpened   : OrderEvent
    data object OnRefreshClicked : OrderEvent
    data class  OnOrderClicked(val orderId: String) : OrderEvent
}

/** One-time effects that the Screen reacts to. */
sealed interface OrderEffect {
    data class ShowError(val message: String) : OrderEffect

    sealed interface Navigation : OrderEffect {
        data class  GoToDetail(val orderId: String) : Navigation
        data object GoBack : Navigation
    }
}

Contract rules

Step 3 — ViewModel

With MviViewModel base class

class OrderViewModel(
    private val getOrdersUseCase: GetOrdersUseCase,
) : MviViewModel<OrderViewState, OrderEvent, OrderEffect>(
    initialState = OrderViewState(),
) {

    override fun onEvent(event: OrderEvent) {
        when (event) {
            OrderEvent.OnScreenOpened,
            OrderEvent.OnRefreshClicked -> loadOrders()
            is OrderEvent.OnOrderClicked -> navigateToDetail(event.orderId)
        }
    }

    private fun loadOrders() {
        viewModelScope.launch {
            updateState { copy(isLoading = true, errorMessage = null) }
            getOrdersUseCase()
                .onSuccess { orders ->
                    updateState { copy(isLoading = false, orders = orders) }
                }
                .onFailure { error ->
                    updateState { copy(isLoading = false) }
                    emitEffect(OrderEffect.ShowError(error.message ?: "Unknown error"))
                }
        }
    }

    private fun navigateToDetail(orderId: String) {
        emitEffect(OrderEffect.Navigation.GoToDetail(orderId))
    }
}

Without base class (flat)

class OrderViewModel(
    private val getOrdersUseCase: GetOrdersUseCase,
) : ViewModel() {

    private val _state = MutableStateFlow(OrderViewState())
    val state: StateFlow<OrderViewState> = _state.asStateFlow()

    private val _sideEffects = Channel<OrderEffect>(Channel.BUFFERED)
    val sideEffects: Flow<OrderEffect> = _sideEffects.receiveAsFlow()

    fun onEvent(event: OrderEvent) {
        when (event) {
            OrderEvent.OnScreenOpened,
            OrderEvent.OnRefreshClicked -> loadOrders()
            is OrderEvent.OnOrderClicked -> navigateToDetail(event.orderId)
        }
    }

    private fun loadOrders() {
        viewModelScope.launch {
            _state.update { it.copy(isLoading = true, errorMessage = null) }
            getOrdersUseCase()
                .onSuccess { orders ->
                    _state.update { it.copy(isLoading = false, orders = orders) }
                }
                .onFailure { error ->
                    _state.update { it.copy(isLoading = false) }
                    _sideEffects.send(OrderEffect.ShowError(error.message ?: "Unknown error"))
                }
        }
    }

    private fun navigateToDetail(orderId: String) {
        viewModelScope.launch { _sideEffects.send(OrderEffect.Navigation.GoToDetail(orderId)) }
    }
}

Step 4 — Screen

@Composable
fun OrderScreen(
    state: OrderViewState,
    onEvent: (OrderEvent) -> Unit,
    sideEffects: Flow<OrderEffect>,
    onNavigation: (OrderEffect.Navigation) -> Unit,
) {
    // Collect side effects — one LaunchedEffect scoped to Unit fires once on entry
    LaunchedEffect(Unit) {
        sideEffects.collect { effect ->
            when (effect) {
                is OrderEffect.Navigation -> onNavigation(effect)
                is OrderEffect.ShowError  -> { /* show snackbar/toast */ }
            }
        }
    }

    // Trigger initial load
    LaunchedEffect(Unit) {
        onEvent(OrderEvent.OnScreenOpened)
    }

    Box(modifier = Modifier.fillMaxSize()) {
        when {
            state.isLoading ->
                CircularProgressIndicator(modifier = Modifier.align(Alignment.Center))
            state.errorMessage != null ->
                ErrorView(
                    message = state.errorMessage,
                    onRetry = { onEvent(OrderEvent.OnRefreshClicked) },
                )
            else ->
                OrderList(
                    orders = state.orders,
                    onOrderClick = { onEvent(OrderEvent.OnOrderClicked(it.id)) },
                )
        }
    }
}

Screen rules

• Receives state, onEvent, sideEffects, onNavigation — never the ViewModel directly
• Stateless and pure: same inputs → same UI output
• No business logic, no coroutines launched manually

Step 5 — Navigation wiring (app layer)

// app/navigation/OrderNavigation.kt

fun NavGraphBuilder.orderNavigation(navController: NavController) {
    composable<OrderRoute> {
        val viewModel: OrderViewModel = viewModel() // or koinViewModel() / hiltViewModel()
        val state by viewModel.state.collectAsStateWithLifecycle()

        OrderScreen(
            state = state,
            onEvent = viewModel::onEvent,
            sideEffects = viewModel.sideEffects,
            onNavigation = { nav ->
                when (nav) {
                    is OrderEffect.Navigation.GoToDetail ->
                        navController.navigate(OrderDetailRoute(nav.orderId))
                    OrderEffect.Navigation.GoBack ->
                        navController.popBackStack()
                }
            },
        )
    }
}

Common State Patterns

Loading / Error / Content

data class ContentViewState(
    val isLoading: Boolean = false,
    val content: ContentData? = null,
    val error: String? = null,
)

// Rendering
when {
    state.isLoading      -> LoadingIndicator()
    state.error != null  -> ErrorView(state.error)
    state.content != null -> ContentView(state.content)
}

Form

data class FormViewState(
    val email: String = "",
    val password: String = "",
    val isSubmitting: Boolean = false,
    val emailError: String? = null,
) {
    // Derived — computed from state, not stored separately
    val isSubmitEnabled: Boolean
        get() = email.isNotBlank() && password.isNotBlank() && !isSubmitting
}

Paginated list

data class ListViewState(
    val items: List<Item> = emptyList(),
    val isLoadingMore: Boolean = false,
    val hasNextPage: Boolean = true,
    val currentPage: Int = 0,
)

Testing

@OptIn(ExperimentalCoroutinesApi::class)
class OrderViewModelTest {

    @get:Rule
    val mainDispatcherRule = MainDispatcherRule()

    private val getOrdersUseCase: GetOrdersUseCase = mockk()
    private lateinit var sut: OrderViewModel

    @Before
    fun setup() {
        sut = OrderViewModel(getOrdersUseCase)
    }

    @Test
    fun `SHOULD show orders WHEN load succeeds`() = runTest {
        // GIVEN
        val orders = listOf(Order("1", "Pizza"))
        coEvery { getOrdersUseCase() } returns Result.success(orders)

        // WHEN
        sut.onEvent(OrderEvent.OnScreenOpened)
        advanceUntilIdle()

        // THEN
        assertEquals(orders, sut.state.value.orders)
        assertFalse(sut.state.value.isLoading)
        assertNull(sut.state.value.errorMessage)
    }

    @Test
    fun `SHOULD emit ShowError WHEN load fails`() = runTest {
        // GIVEN
        coEvery { getOrdersUseCase() } returns Result.failure(RuntimeException("Net error"))

        val effects = mutableListOf<OrderEffect>()
        val job = launch { sut.sideEffects.toList(effects) }

        // WHEN
        sut.onEvent(OrderEvent.OnScreenOpened)
        advanceUntilIdle()
        job.cancel()

        // THEN
        assertTrue(effects.first() is OrderEffect.ShowError)
    }
}

// ── Utility — copy into your test module ─────────────────────────────────────
class MainDispatcherRule(
    val dispatcher: TestCoroutineDispatcher = TestCoroutineDispatcher(),
) : TestWatcher() {
    override fun starting(description: Description?) = Dispatchers.setMain(dispatcher)
    override fun finished(description: Description?) = Dispatchers.resetMain()
}

Anti-Patterns

References

• Android Architecture — UDF
• ViewModel + StateFlow
• Compose state hoisting
• Channel — fire-and-forget effects