KMP Presentation Layer (MVI)

Everything in this layer lives in commonMain and is shared between Android and iOS.

Dependencies

ViewModel, viewModelScope, SavedStateHandle, and collectAsStateWithLifecycle are multiplatform, but must come from the JetBrains artifacts. The Kotlin imports stay androidx.lifecycle.*. The cmp.feature convention plugin adds all of them (see kmp-module-structure).

Never add androidx.lifecycle:lifecycle-*-compose to commonMain — those coordinates are Android-only.

Overview

Every screen has:

1. State — a single data class holding all UI state fields.
2. Action (Intent) — a sealed interface of all user-triggered actions.
3. ViewModel — holds StateFlow<State> and processes Action.
4. Event (optional) — a sealed interface of one-time side effects the ViewModel needs to push to the UI. Only add this when needed (see When to add Events).

State

data class NoteListState(
    val notes: List<NoteUi> = emptyList(),
    val isLoading: Boolean = false,
    val error: UiText? = null
)

Always update state with .update { } — never replace the entire flow:

_state.update { it.copy(isLoading = true) }

Action (Intent)

sealed interface NoteListAction {
    data object OnRefreshClick : NoteListAction
    data class OnNoteClick(val noteId: String) : NoteListAction
    data class OnDeleteNote(val noteId: String) : NoteListAction
}

Event (one-time side effects, optional)

Events exist only when the ViewModel needs to push a one-time side effect to the UI that only the ViewModel knows about. If no such side effect exists for a screen, do not define an Event type, do not create a Channel, and do not expose an events Flow.

When to add an Event

Add an event for a case only the ViewModel can decide, such as:

• Navigating after a successful async operation (e.g., navigate to home after a successful login call completes).
• Showing a snackbar because of a network error that came back from a repository call.
• Triggering a platform side effect after business logic finishes (e.g., copy to clipboard, share sheet, biometric prompt).

When NOT to add an Event

Do not add an event for anything the UI can decide on its own from a click or from state:

• Plain navigation triggered directly by a button click that doesn't need a ViewModel result — navigate directly from the composable's onClick, without a roundtrip through onAction and an event.
• Showing a dialog or bottom sheet whose visibility can live in State as a boolean or nullable value.
• Any UI reaction that can be derived from observing State changes.

If none of the above cases apply to the screen, drop the Event sealed interface, the Channel, and the events Flow entirely. The ObserveAsEvents block in the Root composable is also removed.

Example (when events ARE needed)

sealed interface LoginEvent {
    data object LoginSucceeded : LoginEvent
    data class ShowSnackbar(val message: UiText) : LoginEvent
}

Here LoginSucceeded can only be known after the async login call resolves, and the network error can only be turned into a snackbar message inside the ViewModel — both are legitimate events.

ViewModel

With events (only when actually needed)

class LoginViewModel(
    private val authRepository: AuthRepository
) : ViewModel() {

    private val _state = MutableStateFlow(LoginState())
    val state = _state.asStateFlow()

    private val _events = Channel<LoginEvent>()
    val events = _events.receiveAsFlow()

    fun onAction(action: LoginAction) {
        when (action) {
            is LoginAction.OnLoginClick -> login()
            /* ... */
        }
    }

    private fun login() {
        viewModelScope.launch {
            _state.update { it.copy(isLoading = true) }
            authRepository.login(state.value.email, state.value.password)
                .onSuccess {
                    _state.update { it.copy(isLoading = false) }
                    _events.send(LoginEvent.LoginSucceeded)
                }
                .onFailure { error ->
                    _state.update { it.copy(isLoading = false) }
                    _events.send(LoginEvent.ShowSnackbar(error.toUiText()))
                }
        }
    }
}

Without events (default when nothing needs to be pushed)

class NoteListViewModel(
    private val noteRepository: NoteRepository
) : ViewModel() {

    private val _state = MutableStateFlow(NoteListState())
    val state = _state.asStateFlow()

    fun onAction(action: NoteListAction) {
        when (action) {
            is NoteListAction.OnRefreshClick -> loadNotes()
            /* OnNoteClick is NOT handled here — the composable navigates directly on click */
        }
    }

    private fun loadNotes() {
        viewModelScope.launch {
            _state.update { it.copy(isLoading = true) }
            noteRepository.getNotes()
                .onSuccess { notes ->
                    _state.update { it.copy(notes = notes.map { it.toNoteUi() }, isLoading = false) }
                }
                .onFailure { error ->
                    _state.update { it.copy(isLoading = false, error = error.toUiText()) }
                }
        }
    }
}

Note how the error surfaces via State.error instead of an event — observing state is enough because the UI just needs to render it.

Coroutine Dispatchers

Do not inject unless the class is unit-tested and dispatches to a non-main dispatcher. For ViewModel tests, use Dispatchers.setMain(UnconfinedTestDispatcher()) in test setup.

For blocking code that doesn't support suspension, wrap it:

// import kotlinx.coroutines.IO  ← required for Dispatchers.IO in common code
suspend fun compressImage(bytes: ByteArray): ByteArray = withContext(Dispatchers.IO) {
    // blocking compression logic
}

Only inject CoroutineDispatcher when:

1. The class dispatches to a non-main dispatcher (e.g., IO), AND
2. That class is directly unit-tested.

Mapping Errors to UI Strings

UiText (core:presentation) wraps strings that originate from — or could originate from — a string resource:

// import org.jetbrains.compose.resources.StringResource
// import org.jetbrains.compose.resources.stringResource
// import org.jetbrains.compose.resources.getString
sealed interface UiText {
    data class DynamicString(val value: String) : UiText
    class Resource(val id: StringResource, val args: Array<Any> = emptyArray()) : UiText

    @Composable
    fun asString(): String = when (this) {
        is DynamicString -> value
        is Resource -> stringResource(id, *args)
    }

    suspend fun asStringAsync(): String = when (this) {
        is DynamicString -> value
        is Resource -> getString(id, *args)
    }
}

There are no Int resource IDs in shared code. The ID is a Compose Multiplatform StringResource (Res.string.*), and the variant is named UiText.Resource so it does not clash with that library type. Use asString() inside composables and asStringAsync() outside composition (e.g. when showing a snackbar from an event).

When to use UiText: For any string that comes from a string resource, could be localized, or might be either a resource or a dynamic value depending on context (e.g., error messages that map to Res.string.*).

When to use plain String: For values that are always dynamic and never come from resources — e.g., a user's name, a formatted date, a currency amount. These should be exposed as String directly in the state or UI model.

// UiText — error message that maps to a string resource
data class NoteListState(
    val error: UiText? = null
)

// Plain String — always dynamic, never a resource
data class NoteUi(
    val authorName: String,
    val formattedDate: String
)

Define DataError.toUiText() extension functions in core:presentation (or feature presentation) that map error enums to UiText.Resource.

UI Model (Presentation Model)

When a domain model needs UI-specific formatting (dates, units, currency), create a dedicated UI model in the presentation layer:

data class NoteUi(
    val id: String,
    val title: String,
    val formattedDate: String  // e.g. "Mar 15, 2026"
)

fun Note.toNoteUi(): NoteUi = NoteUi(
    id = id,
    title = title,
    formattedDate = date.format(...)  // kotlinx-datetime formatting — java.time / SimpleDateFormat don't exist in commonMain
)

UI models are always suffixed with Ui (e.g., NoteUi, TodoItemUi).

Composable Structure

Both the Root and Screen composable live in the same file (e.g., NoteListScreen.kt).

Root Composable (suffixed Root)

Receives the ViewModel (via koinViewModel()) and any callbacks needed for navigation. Observes events only when the ViewModel exposes an events Flow. Passes state and onAction down.

For plain navigation that a button click triggers directly, invoke the navigation callback from the Screen composable's onClick — do not route it through onAction and an event.

Screen Composable (suffixed Screen)

Receives state, onAction, and any direct navigation callbacks that don't need a ViewModel roundtrip. No ViewModel reference. Can be previewed independently — the @Preview lives in commonMain in the same file.

Example — no events (navigation happens directly on click)

// NoteListScreen.kt — Root + Screen in a single file

@Composable
fun NoteListRoot(
    onNavigateToDetail: (String) -> Unit,
    viewModel: NoteListViewModel = koinViewModel()
) {
    val state by viewModel.state.collectAsStateWithLifecycle()

    NoteListScreen(
        state = state,
        onAction = viewModel::onAction,
        onNoteClick = onNavigateToDetail
    )
}

@Composable
fun NoteListScreen(
    state: NoteListState,
    onAction: (NoteListAction) -> Unit,
    onNoteClick: (String) -> Unit
) { /* onNoteClick fires directly from the list item's onClick */ }

@Preview
@Composable
private fun NoteListScreenPreview() {
    NoteListScreen(state = NoteListState(), onAction = {}, onNoteClick = {})
}

Example — with events (one-time side effect only the ViewModel knows)

// LoginScreen.kt

@Composable
fun LoginRoot(
    onLoginSuccess: () -> Unit,
    viewModel: LoginViewModel = koinViewModel()
) {
    val state by viewModel.state.collectAsStateWithLifecycle()

    ObserveAsEvents(viewModel.events) { event ->
        when (event) {
            LoginEvent.LoginSucceeded -> onLoginSuccess()
            is LoginEvent.ShowSnackbar -> { /* show snackbar */ }
        }
    }

    LoginScreen(
        state = state,
        onAction = viewModel::onAction
    )
}

Process Death

When a screen involves complex forms or critical user input, restore essential fields using SavedStateHandle:

class NoteEditorViewModel(
    private val savedStateHandle: SavedStateHandle,
    private val noteRepository: NoteRepository
) : ViewModel() {
    private val _state = MutableStateFlow(
        NoteEditorState(
            title = savedStateHandle["title"] ?: "",
            body = savedStateHandle["body"] ?: ""
        )
    )

    fun onAction(action: NoteEditorAction) {
        when (action) {
            is NoteEditorAction.OnTitleChange -> {
                savedStateHandle["title"] = action.title
                _state.update { it.copy(title = action.title) }
            }
        }
    }
}

Only save what truly matters after process death — not the entire state.

Platform notes:

• SavedStateHandle compiles in commonMain and is injected by Koin's viewModelOf on both platforms.
• On Android it survives process death as usual.
• On iOS nothing is restored automatically after the app is terminated. The handle only lives as long as its nav back stack entry. Anything that must survive an iOS app kill has to be persisted explicitly (DataStore / Room).
• Only store values that can be saved on both platforms: primitives, String, and lists/arrays of those. No Parcelable — store structured values as a KotlinX-serialized String.

Naming Conventions

Checklist: Adding a New Screen

• Define State and Action in feature:presentation
• Decide whether an Event type is needed (only for one-time side effects the ViewModel alone can determine — see When to add an Event). If not, skip the Event sealed interface, the Channel, and the events Flow entirely.
• Implement ViewModel in feature:presentation (expose events Flow only if events exist)
• Create <Screen>Root composable (holds ViewModel; adds ObserveAsEvents only when events exist)
• Create <Screen>Screen composable (pure state + onAction + any direct navigation callbacks, previewable)
• Route plain button-click navigation directly through composable callbacks — not through onAction + event
• Map any domain errors to UiText via extension functions
• Add SavedStateHandle for any form fields that must survive process death