Compose Multiplatform Patterns

Patterns for building shared UI across Android, iOS, Desktop, and Web using Compose Multiplatform and Jetpack Compose. Covers state management, navigation, theming, and performance.

When to Activate

• Building Compose UI (Jetpack Compose or Compose Multiplatform)
• Managing UI state with ViewModels and Compose state
• Implementing navigation in KMP or Android projects
• Designing reusable composables and design systems
• Optimizing recomposition and rendering performance

State Management

ViewModel + Single State Object

Use a single data class for screen state. Expose it as StateFlow and collect in Compose:

kotlin
1data class ItemListState(
2    val items: List<Item> = emptyList(),
3    val isLoading: Boolean = false,
4    val error: String? = null,
5    val searchQuery: String = ""
6)
7
8class ItemListViewModel(
9    private val getItems: GetItemsUseCase
10) : ViewModel() {
11    private val _state = MutableStateFlow(ItemListState())
12    val state: StateFlow<ItemListState> = _state.asStateFlow()
13
14    fun onSearch(query: String) {
15        _state.update { it.copy(searchQuery = query) }
16        loadItems(query)
17    }
18
19    private fun loadItems(query: String) {
20        viewModelScope.launch {
21            _state.update { it.copy(isLoading = true) }
22            getItems(query).fold(
23                onSuccess = { items -> _state.update { it.copy(items = items, isLoading = false) } },
24                onFailure = { e -> _state.update { it.copy(error = e.message, isLoading = false) } }
25            )
26        }
27    }
28}

Collecting State in Compose

kotlin
1@Composable
2fun ItemListScreen(viewModel: ItemListViewModel = koinViewModel()) {
3    val state by viewModel.state.collectAsStateWithLifecycle()
4
5    ItemListContent(
6        state = state,
7        onSearch = viewModel::onSearch
8    )
9}
10
11@Composable
12private fun ItemListContent(
13    state: ItemListState,
14    onSearch: (String) -> Unit
15) {
16    // Stateless composable — easy to preview and test
17}

Event Sink Pattern

For complex screens, use a sealed interface for events instead of multiple callback lambdas:

kotlin
1sealed interface ItemListEvent {
2    data class Search(val query: String) : ItemListEvent
3    data class Delete(val itemId: String) : ItemListEvent
4    data object Refresh : ItemListEvent
5}
6
7// In ViewModel
8fun onEvent(event: ItemListEvent) {
9    when (event) {
10        is ItemListEvent.Search -> onSearch(event.query)
11        is ItemListEvent.Delete -> deleteItem(event.itemId)
12        is ItemListEvent.Refresh -> loadItems(_state.value.searchQuery)
13    }
14}
15
16// In Composable — single lambda instead of many
17ItemListContent(
18    state = state,
19    onEvent = viewModel::onEvent
20)

Navigation

Type-Safe Navigation (Compose Navigation 2.8+)

Define routes as @Serializable objects:

kotlin
1@Serializable data object HomeRoute
2@Serializable data class DetailRoute(val id: String)
3@Serializable data object SettingsRoute
4
5@Composable
6fun AppNavHost(navController: NavHostController = rememberNavController()) {
7    NavHost(navController, startDestination = HomeRoute) {
8        composable<HomeRoute> {
9            HomeScreen(onNavigateToDetail = { id -> navController.navigate(DetailRoute(id)) })
10        }
11        composable<DetailRoute> { backStackEntry ->
12            val route = backStackEntry.toRoute<DetailRoute>()
13            DetailScreen(id = route.id)
14        }
15        composable<SettingsRoute> { SettingsScreen() }
16    }
17}

Dialog and Bottom Sheet Navigation

Use dialog() and overlay patterns instead of imperative show/hide:

kotlin
1NavHost(navController, startDestination = HomeRoute) {
2    composable<HomeRoute> { /* ... */ }
3    dialog<ConfirmDeleteRoute> { backStackEntry ->
4        val route = backStackEntry.toRoute<ConfirmDeleteRoute>()
5        ConfirmDeleteDialog(
6            itemId = route.itemId,
7            onConfirm = { navController.popBackStack() },
8            onDismiss = { navController.popBackStack() }
9        )
10    }
11}

Composable Design

Slot-Based APIs

Design composables with slot parameters for flexibility:

kotlin
1@Composable
2fun AppCard(
3    modifier: Modifier = Modifier,
4    header: @Composable () -> Unit = {},
5    content: @Composable ColumnScope.() -> Unit,
6    actions: @Composable RowScope.() -> Unit = {}
7) {
8    Card(modifier = modifier) {
9        Column {
10            header()
11            Column(content = content)
12            Row(horizontalArrangement = Arrangement.End, content = actions)
13        }
14    }
15}

Modifier Ordering

Modifier order matters — apply in this sequence:

kotlin
1Text(
2    text = "Hello",
3    modifier = Modifier
4        .padding(16.dp)          // 1. Layout (padding, size)
5        .clip(RoundedCornerShape(8.dp))  // 2. Shape
6        .background(Color.White) // 3. Drawing (background, border)
7        .clickable { }           // 4. Interaction
8)

KMP Platform-Specific UI

expect/actual for Platform Composables

kotlin
1// commonMain
2@Composable
3expect fun PlatformStatusBar(darkIcons: Boolean)
4
5// androidMain
6@Composable
7actual fun PlatformStatusBar(darkIcons: Boolean) {
8    val systemUiController = rememberSystemUiController()
9    SideEffect { systemUiController.setStatusBarColor(Color.Transparent, darkIcons) }
10}
11
12// iosMain
13@Composable
14actual fun PlatformStatusBar(darkIcons: Boolean) {
15    // iOS handles this via UIKit interop or Info.plist
16}

Performance

Stable Types for Skippable Recomposition

Mark classes as @Stable or @Immutable when all properties are stable:

kotlin
1@Immutable
2data class ItemUiModel(
3    val id: String,
4    val title: String,
5    val description: String,
6    val progress: Float
7)

Use key() and Lazy Lists Correctly

kotlin
1LazyColumn {
2    items(
3        items = items,
4        key = { it.id }  // Stable keys enable item reuse and animations
5    ) { item ->
6        ItemRow(item = item)
7    }
8}

Defer Reads with derivedStateOf

kotlin
1val listState = rememberLazyListState()
2val showScrollToTop by remember {
3    derivedStateOf { listState.firstVisibleItemIndex > 5 }
4}

Avoid Allocations in Recomposition

kotlin
1// BAD — new lambda and list every recomposition
2items.filter { it.isActive }.forEach { ActiveItem(it, onClick = { handle(it) }) }
3
4// GOOD — key each item so callbacks stay attached to the right row
5val activeItems = remember(items) { items.filter { it.isActive } }
6activeItems.forEach { item ->
7    key(item.id) {
8        ActiveItem(item, onClick = { handle(item) })
9    }
10}

Theming

Material 3 Dynamic Theming

kotlin
1@Composable
2fun AppTheme(
3    darkTheme: Boolean = isSystemInDarkTheme(),
4    dynamicColor: Boolean = true,
5    content: @Composable () -> Unit
6) {
7    val colorScheme = when {
8        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
9            if (darkTheme) dynamicDarkColorScheme(LocalContext.current)
10            else dynamicLightColorScheme(LocalContext.current)
11        }
12        darkTheme -> darkColorScheme()
13        else -> lightColorScheme()
14    }
15
16    MaterialTheme(colorScheme = colorScheme, content = content)
17}

Anti-Patterns to Avoid

• Using mutableStateOf in ViewModels when MutableStateFlow with collectAsStateWithLifecycle is safer for lifecycle
• Passing NavController deep into composables — pass lambda callbacks instead
• Heavy computation inside @Composable functions — move to ViewModel or remember {}
• Using LaunchedEffect(Unit) as a substitute for ViewModel init — it re-runs on configuration change in some setups
• Creating new object instances in composable parameters — causes unnecessary recomposition

References

See skill: android-clean-architecture for module structure and layering. See skill: kotlin-coroutines-flows for coroutine and Flow patterns.