--- name: compose-multiplatform-patterns description: Compose Multiplatform and Jetpack Compose patterns for KMP projects — state management, navigation, theming, performance, and platform-specific UI. Use when building Compose or Jetpack Compose UI, state, navigation, or theming in a KMP project. metadata: origin: ECC title: compose-multiplatform-patterns canonical_url: https://skilld.dev/gh/affaan-m/ecc/compose-multiplatform-patterns last_updated: 2026-10-03T00:03:21.000Z --- > Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt) > **Skill from skilld.dev.** Follow the user's requested action. > If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it. > Otherwise, follow the instructions below for this session. You do not need to install anything. > > If the user asked to install this Skill, run `npx skilld install affaan-m/ecc/compose-multiplatform-patterns`. Install writes the Skill files into the project, so every session loads them. > > ## Fork workflow > > A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation. > 1. Check `./skills/compose-multiplatform-patterns`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target. > 2. Read [source metadata](https://skilld.dev/api/v1/skills/affaan-m/ecc/compose-multiplatform-patterns) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit. > 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call: > > ```sh > git init --quiet "$temporary_dir" > git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit" > git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD > ``` > > Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop. > 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/compose-multiplatform-patterns`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md. > Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical. > 5. In the project root, run `skilld install ./skills/compose-multiplatform-patterns --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/compose-multiplatform-patterns --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure. > 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks. # 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 data class ItemListState( val items: List = emptyList(), val isLoading: Boolean = false, val error: String? = null, val searchQuery: String = "" ) class ItemListViewModel( private val getItems: GetItemsUseCase ) : ViewModel() { private val _state = MutableStateFlow(ItemListState()) val state: StateFlow = _state.asStateFlow() fun onSearch(query: String) { _state.update { it.copy(searchQuery = query) } loadItems(query) } private fun loadItems(query: String) { viewModelScope.launch { _state.update { it.copy(isLoading = true) } getItems(query).fold( onSuccess = { items -> _state.update { it.copy(items = items, isLoading = false) } }, onFailure = { e -> _state.update { it.copy(error = e.message, isLoading = false) } } ) } } } ``` ### Collecting State in Compose ```kotlin @Composable fun ItemListScreen(viewModel: ItemListViewModel = koinViewModel()) { val state by viewModel.state.collectAsStateWithLifecycle() ItemListContent( state = state, onSearch = viewModel::onSearch ) } @Composable private fun ItemListContent( state: ItemListState, onSearch: (String) -> Unit ) { // Stateless composable — easy to preview and test } ``` ### Event Sink Pattern For complex screens, use a sealed interface for events instead of multiple callback lambdas: ```kotlin sealed interface ItemListEvent { data class Search(val query: String) : ItemListEvent data class Delete(val itemId: String) : ItemListEvent data object Refresh : ItemListEvent } // In ViewModel fun onEvent(event: ItemListEvent) { when (event) { is ItemListEvent.Search -> onSearch(event.query) is ItemListEvent.Delete -> deleteItem(event.itemId) is ItemListEvent.Refresh -> loadItems(_state.value.searchQuery) } } // In Composable — single lambda instead of many ItemListContent( state = state, onEvent = viewModel::onEvent ) ``` ## Navigation ### Type-Safe Navigation (Compose Navigation 2.8+) Define routes as `@Serializable` objects: ```kotlin @Serializable data object HomeRoute @Serializable data class DetailRoute(val id: String) @Serializable data object SettingsRoute @Composable fun AppNavHost(navController: NavHostController = rememberNavController()) { NavHost(navController, startDestination = HomeRoute) { composable { HomeScreen(onNavigateToDetail = { id -> navController.navigate(DetailRoute(id)) }) } composable { backStackEntry -> val route = backStackEntry.toRoute() DetailScreen(id = route.id) } composable { SettingsScreen() } } } ``` ### Dialog and Bottom Sheet Navigation Use `dialog()` and overlay patterns instead of imperative show/hide: ```kotlin NavHost(navController, startDestination = HomeRoute) { composable { /* ... */ } dialog { backStackEntry -> val route = backStackEntry.toRoute() ConfirmDeleteDialog( itemId = route.itemId, onConfirm = { navController.popBackStack() }, onDismiss = { navController.popBackStack() } ) } } ``` ## Composable Design ### Slot-Based APIs Design composables with slot parameters for flexibility: ```kotlin @Composable fun AppCard( modifier: Modifier = Modifier, header: @Composable () -> Unit = {}, content: @Composable ColumnScope.() -> Unit, actions: @Composable RowScope.() -> Unit = {} ) { Card(modifier = modifier) { Column { header() Column(content = content) Row(horizontalArrangement = Arrangement.End, content = actions) } } } ``` ### Modifier Ordering Modifier order matters — apply in this sequence: ```kotlin Text( text = "Hello", modifier = Modifier .padding(16.dp) // 1. Layout (padding, size) .clip(RoundedCornerShape(8.dp)) // 2. Shape .background(Color.White) // 3. Drawing (background, border) .clickable { } // 4. Interaction ) ``` ## KMP Platform-Specific UI ### expect/actual for Platform Composables ```kotlin // commonMain @Composable expect fun PlatformStatusBar(darkIcons: Boolean) // androidMain @Composable actual fun PlatformStatusBar(darkIcons: Boolean) { val systemUiController = rememberSystemUiController() SideEffect { systemUiController.setStatusBarColor(Color.Transparent, darkIcons) } } // iosMain @Composable actual fun PlatformStatusBar(darkIcons: Boolean) { // iOS handles this via UIKit interop or Info.plist } ``` ## Performance ### Stable Types for Skippable Recomposition Mark classes as `@Stable` or `@Immutable` when all properties are stable: ```kotlin @Immutable data class ItemUiModel( val id: String, val title: String, val description: String, val progress: Float ) ``` ### Use `key()` and Lazy Lists Correctly ```kotlin LazyColumn { items( items = items, key = { it.id } // Stable keys enable item reuse and animations ) { item -> ItemRow(item = item) } } ``` ### Defer Reads with `derivedStateOf` ```kotlin val listState = rememberLazyListState() val showScrollToTop by remember { derivedStateOf { listState.firstVisibleItemIndex > 5 } } ``` ### Avoid Allocations in Recomposition ```kotlin // BAD — new lambda and list every recomposition items.filter { it.isActive }.forEach { ActiveItem(it, onClick = { handle(it) }) } // GOOD — key each item so callbacks stay attached to the right row val activeItems = remember(items) { items.filter { it.isActive } } activeItems.forEach { item -> key(item.id) { ActiveItem(item, onClick = { handle(item) }) } } ``` ## Theming ### Material 3 Dynamic Theming ```kotlin @Composable fun AppTheme( darkTheme: Boolean = isSystemInDarkTheme(), dynamicColor: Boolean = true, content: @Composable () -> Unit ) { val colorScheme = when { dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> { if (darkTheme) dynamicDarkColorScheme(LocalContext.current) else dynamicLightColorScheme(LocalContext.current) } darkTheme -> darkColorScheme() else -> lightColorScheme() } MaterialTheme(colorScheme = colorScheme, content = content) } ``` ## 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.