Skip to content
Skills Library
Programming · Building & coding

jetpack-compose

/jetpack-compose

Jetpack Compose for native Android UI. Covers @Composable functions, state, side effects, ViewModel + Compose, Hilt DI, Navigation Compose, Material 3 with Dynamic Color (Material You), Compose for Wear OS, Compose previews, and Android lifecycle integration (Activity, Fragment interop). USE WHEN: user mentions "Jetpack Compose", "@Composable" in Android-only context, "ViewModel", "Hilt", "Navigation Compose", "Material You", "Dynamic Color", "Compose preview", "AndroidView", "rememberLauncherForActivityResult", "Compose Wear OS" DO NOT USE FOR: Cross-platform Compose - use `frontend-framework

Licence
MIT
Last repository change
21.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Jetpack Compose for native Android UI. Covers @Composable functions, state, side effects, ViewModel + Compose, Hilt DI, Navigation Compose, Material 3 with Dynamic Color (Material You), Compose for Wear OS, Compose previews, and Android lifecycle integration (Activity, Fragment interop). USE WHEN: user mentions "Jetpack Compose", "@Composable" in Android-only context, "ViewModel", "Hilt", "Navigation Compose", "Material You", "Dynamic Color", "Compose preview", "AndroidView", "rememberLauncherForActivityResult", "Compose Wear OS" DO NOT USE FOR: Cross-platform Compose - use `frontend-framework

Triggers from the description

Jetpack Compose@ComposableViewModelHiltNavigation ComposeMaterial YouDynamic ColorCompose preview
Original author description

Jetpack Compose for native Android UI. Covers @Composable functions, state, side effects, ViewModel + Compose, Hilt DI, Navigation Compose, Material 3 with Dynamic Color (Material You), Compose for Wear OS, Compose previews, and Android lifecycle integration (Activity, Fragment interop). USE WHEN: user mentions "Jetpack Compose", "@Composable" in Android-only context, "ViewModel", "Hilt", "Navigation Compose", "Material You", "Dynamic Color", "Compose preview", "AndroidView", "rememberLauncherForActivityResult", "Compose Wear OS" DO NOT USE FOR: Cross-platform Compose - use `frontend-framework

How it works

  1. Setup
  2. Activity Entry Point
  3. ViewModel + StateFlow + Compose
  4. Material 3 + Dynamic Color (Material You)
  5. Navigation Compose (Type-Safe Routes — 2.8+)
  6. Side Effects (Android-specific)
  7. Hilt + Compose
  8. Common UI Patterns
  9. Compose Previews
  10. Dialogs and Bottom Sheets
Original SKILL.md headings · 555 lines, 1,714 words
SKILL.md preview
---
name: jetpack-compose
description: |
  Jetpack Compose for native Android UI. Covers @Composable functions, state,
  side effects, ViewModel + Compose, Hilt DI, Navigation Compose, Material 3 with
  Dynamic Color (Material You), Compose for Wear OS, Compose previews, and Android
  lifecycle integration (Activity, Fragment interop).

  USE WHEN: user mentions "Jetpack Compose", "@Composable" in Android-only context,
  "ViewModel", "Hilt", "Navigation Compose", "Material You", "Dynamic Color",
  "Compose preview", "AndroidView", "rememberLauncherForActivityResult",
  "Compose Wear OS"

  DO NOT USE FOR: Cross-platform Compose - use `frontend-frameworks/compose-multiplatform`
  DO NOT USE FOR: Kotlin language fundamentals - use `languages/kotlin`
  DO NOT USE FOR: Android non-UI APIs (Keystore, NFC, etc) - use `mobile/android-native`
allowed-tools: Read, Grep, Glob, Write, Edit
---
# Jetpack Compose (Android)

> **References**: [state-effects.md](quick-ref/state-effects.md) for ViewModel + Compose, side-effect APIs, snapshot system. [navigation.md](quick-ref/navigation.md) for Navigation Compose 2.8+ with type-safe routes, deep links, multi-stack. [interop.md](quick-ref/interop.md) for AndroidView/ComposeView interop, Activity Result Contracts, Fragment integration.
>
> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `jetpack-compose`.

## Setup

```kotlin
// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android") version "2.2.0"
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0"   // required for Kotlin 2.x
    id("com.google.devtools.ksp")
    id("dagger.hilt.android.plugin")
}

android {
    buildFeatures { compose = true }
    composeOptions {
        // Compose Compiler is now part of Kotlin 2.x — no kotlinCompilerExtensionVersion needed
    }
}

dependencies {
    val composeBom = platform("androidx.compose:compose-bom:2025.01.00")
    implementation(composeBom)
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
    implementation("androidx.compose.material:material-icons-extended")
    implementation("androidx.compose.ui:ui-tooling-preview")
    debugImplementation("androidx.compose.ui:ui-tooling")

    implementation("androidx.activity:activity-compose:1.10.0")
    implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.9.0")
    implementation("androidx.lifecycle:lifecycle-runtime-compose:2.9.0")
    implementation("androidx.navigation:navigation-compose:2.8.5")
    implementation("androidx.hilt:hilt-navigation-compose:1.2.0")
    implementation("com.google.dagger:hilt-android:2.55")
    ksp("com.google.dagger:hilt-compiler:2.55")
}
```

## Activity Entry Point

```kotlin
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()                         // draws under status/nav bars
        setContent {
            BhodlTheme {
                AppNavHost()
            }
        }
    }
}
```

`enableEdgeToEdge()` (Activity 1.8+) is the modern way to configure edge-to-edge — replaces `WindowCompat.setDecorFitsSystemWindows(window, false)`.

## ViewModel + StateFlow + Compose

```kotlin
@HiltViewModel
class WalletViewModel @Inject constructor(
    private val repo: WalletRepository,
    savedStateHandle: SavedStateHandle,
) : ViewModel() {

    private val walletId: String = savedStateHandle["walletId"] ?: error("missing walletId")

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

    init { load() }

    fun load() {
        viewModelScope.launch {
            _state.value = UiState.Loading
            runCatching { repo.getWallet(walletId) }
                .onSuccess { _state.value = UiState.Success(it) }
                .onFailure { _state.value = UiState.Error(it.message ?: "unknown") }
        }
    }
}

@Composable
fun WalletScreen(
    viewModel: WalletViewModel = hiltViewModel(),
) {
    val state by viewModel.state.collectAsStateWithLifecycle()

    when (val s = state) {
        UiState.Loading -> CircularProgressIndicator()
        is UiState.Success -> WalletContent(s.wallet, onRefresh = viewModel::load)
        is UiState.Error -> ErrorView(s.message, onRetry = viewModel::load)
    }
}
```

`collectAsStateWithLifecycle()` (from `lifecycle-runtime-compose`) is **preferred over `collectAsState`** — automatically pauses collection when screen is in background, prevents wasted work and battery drain.

## Material 3 + Dynamic Color (Material You)

```kotlin
@Composable
fun BhodlTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,                  // Material You on Android 12+
    content: @Composable () -> Unit,
) {
    val context = LocalContext.current
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S ->
            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
        darkTheme -> DarkColors
        else -> LightColors
    }

    MaterialTheme(
        colorScheme = colorScheme,
        typography = bhodlTypography,
        shapes = bhodlShapes,
        content = content,
    )
}
```

For status/nav bar tinting in edge-to-edge:

```kotlin
val view = LocalView.current
if (!view.isInEditMode) {
    SideEffect {
        val window = (view.context as Activity).window
        WindowCompat.getInsetsController(window, view).isAppearanceLightStatusBars = !darkTheme
    }
}
```

## Navigation Compose (Type-Safe Routes — 2.8+)

```kotlin
@Serializable
data object HomeRoute

@Serializable
data class WalletDetailRoute(val walletId: String)

@Composable
fun AppNavHost() {
    val navController = rememberNavController()

    NavHost(
        navController = navController,
        startDestination = HomeRoute,
    ) {
        composable<HomeRoute> {
            HomeScreen(
                onWalletClick = { id -> navController.navigate(WalletDetailRoute(id)) },
            )
        }
        composable<WalletDetailRoute> { backStackEntry ->
            val route: WalletDetailRoute = backStackEntry.toRoute()
            WalletDetailScreen(
                walletId = route.walletId,
                onBack = { navController.popBackStack() },
            )
        }
    }
}
```

Type-safe routes (since Navigation Compose 2.8) replace string-based routes — no more typo-driven crashes.

For nested graphs:

```kotlin
@Serializable data object SettingsGraph
@Serializable data object ProfileSettingsRoute

NavHost(navController = nav, startDestination = HomeRoute) {
    navigation<SettingsGraph>(startDestination = ProfileSettingsRoute) {
        composable<ProfileSettingsRoute> { ProfileSettings() }
        composable<NotificationSettingsRoute> { NotificationSettings() }
    }
}
```

See [navigation.md](quick-ref/navigation.md) for deep linking, multi-stack bottom nav, dialog/bottom-sheet destinations.

## Side Effects (Android-specific)

| API | Use case |
|---|---|
| `LaunchedEffect(key)` | Suspending work, cancels on key change |
| `DisposableEffect(key)` | Setup with cleanup (lifecycle observer, BroadcastReceiver) |
| `LifecycleEventEffect(event)` | React to specific Lifecycle events (ON_RESUME, ON_PAUSE) |
| `LifecycleResumeEffect` / `LifecycleStartEffect` | Lifecycle-scoped effect with auto-pause |
| `rememberLauncherForActivityResult` | Permissions, file picker, take photo |
| `BackHandler { }` | Intercept system back button |

```kotlin
@Composable
fun CameraScreen() {
    val context = LocalContext.current

    val cameraPermissionLauncher = rememberLauncherForActivityResult(
        contract = ActivityResultContracts.RequestPermission(),
        onResult = { granted -> /* ... */ },
    )

    LaunchedEffect(Unit) {
        cameraPermissionLauncher.launch(Manifest.permission.CAMERA)
    }
}

@Composable
fun ProcessLifecycleObserver(onResume: () -> Unit) {
    LifecycleResumeEffect(Unit) {
        onResume()
        onPauseOrDispose { /* cleanup */ }
    }
}

@Composable
fun ConfirmExit(onExit: () -> Unit) {
    BackHandler { onExit() }
}
```

## Hilt + Compose

```kotlin
// Module
@Module
@InstallIn(SingletonComponent::class)
object AppModule {
    @Provides @Singleton
    fun provideWalletRepository(api: WalletApi, db: AppDatabase): WalletRepository =
        WalletRepositoryImpl(api, db)
}

// ViewModel
@HiltViewModel
class WalletViewModel @Inject constructor(
    private val repo: WalletRepository,
) : ViewModel() { /* ... */ }

// Composable injection
@Composable
fun WalletScreen(viewModel: WalletViewModel = hiltViewModel()) { /* ... */ }
```

For nested `NavHost` with Hilt-scoped ViewModel:

```kotlin
@Composable
fun NestedScreen(navBackStackEntry: NavBackStackEntry) {
    val viewModel: NestedViewModel = hiltViewModel(navBackStackEntry)
    /* ViewModel scoped to this nav destination */
}
```

## Common UI Patterns

### Scaffold with TopAppBar

```kotlin
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun WalletDetailScreen(walletId: String, onBack: () -> Unit) {
    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("Wallet") },
                navigationIcon = {
                    IconButton(onClick = onBack) {
                        Icon(Icons.AutoMirrored.Filled.ArrowBack, "Back")
                    }
                },
                actions = {
                    IconButton(onClick = { /* share */ }) {
                        Icon(Icons.Default.Share, "Share")
                    }
                },
            )
        },
        floatingActionButton = {
            FloatingActionButton(onClick = { /* send */ }) {
                Icon(Icons.Default.Send, "Send")
            }
        },
    ) { padding ->
        Column(Modifier.padding(padding)) { /* content */ }
    }
}
```

### LazyColumn with key

```kotlin
@Composable
fun TransactionList(transactions: List<Transaction>, onClick: (String) -> Unit) {
    LazyColumn(
        contentPadding = PaddingValues(16.dp),
        verticalArrangement = Arrangement.spacedBy(8.dp),
    ) {
        items(
            items = transactions,
            key = { it.id },                          // stable identity
            contentType = { it.type },                // recycle composables by type
        ) { tx ->
            TransactionItem(tx, onClick = { onClick(tx.id) })
        }
    }
}
```

### Pull to Refresh

```kotlin
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun WalletList(viewModel: WalletViewModel) {
    val state by viewModel.state.collectAsStateWithLifecycle()
    val isRefreshing = state is UiState.Loading

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = viewModel::refresh,
    ) {
        LazyColumn { /* ... */ }
    }
}
```

## Compose Previews

```kotlin
@Preview(name = "Light", showBackground = true)
@Preview(name = "Dark", uiMode = Configuration.UI_MODE_NIGHT_YES)
@Preview(name = "Phone", device = Devices.PIXEL_7, showSystemUi = true)
@Composable
fun WalletItemPreview() {
    BhodlTheme {
        WalletItem(
            wallet = Wallet(id = "1", name = "Main", balance = 100_000),
            onClick = {},
        )
    }
}

// Multi-preview annotation
annotation class ThemeAndFontScalePreviews
@ThemeAndFontScalePreviews
@Preview(name = "Light", showBackground = true)
@Preview(name = "Dark", uiMode = Configuration.UI_MODE_NIGHT_YES)
@Preview(name = "Large Font", fontScale = 1.5f)
@Preview(name = "Small Font", fontScale = 0.8f)
@Composable
fun MyPreviews() { /* ... */ }
```

For interactive previews: tap "Interactive Mode" in Android Studio. For animation previews: tap "Animation Inspector".

## Dialogs and Bottom Sheets

```kotlin
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun SendBottomSheet(onDismiss: () -> Unit, onSend: (String, Long) -> Unit) {
    val sheetState = rememberModalBottomSheetState(skipPartiallyExpanded = false)
    val scope = rememberCoroutineScope()

    ModalBottomSheet(
        onDismissRequest = onDismiss,
        sheetState = sheetState,
    ) {
        SendForm(onSend = { addr, amt ->
            scope.launch { sheetState.hide() }
                .invokeOnCompletion {
                    if (!sheetState.isVisible) onDismiss()
                    onSend(addr, amt)
                }
        })
    }
}

@Composable
fun ConfirmDialog(title: String, text: String, onConfirm: () -> Unit, onDismiss: () -> Unit) {
    AlertDialog(
        onDismissRequest = onDismiss,
        title = { Text(title) },
        text = { Text(text) },
        confirmButton = { TextButton(onClick = onConfirm) { Text("Confirm") } },
        dismissButton = { TextButton(onClick = onDismiss) { Text("Cancel") } },
    )
}
```

## Permissions

Use **Accompanist Permissions** (or roll your own with `rememberLauncherForActivityResult`):

```kotlin
implementation("com.google.accompanist:accompanist-permissions:0.36.0")
```

```kotlin
@OptIn(ExperimentalPermissionsApi::class)
@Composable
fun CameraPermissionGate(content: @Composable () -> Unit) {
    val cameraPermission = rememberPermissionState(Manifest.permission.CAMERA)

    when {
        cameraPermission.status.isGranted -> content()
        cameraPermission.status.shouldShowRationale -> RationaleScreen(
            onRequest = { cameraPermission.launchPermissionRequest() }
        )
        else -> RequestScreen(
            onRequest = { cameraPermission.launchPermissionRequest() }
        )
    }
}
```

## Performance

### Stability Annotations

```kotlin
@Immutable
data class WalletUiState(
    val wallets: List<Wallet>,
    val balance: Long,
)

@Stable
interface WalletActions {
    fun onSend()
    fun onReceive()
}
```

`@Immutable` → all fields immutable, treat as stable. `@Stable` → mutable but predictable equality. Both help Compose skip recomposition.

### Compose Compiler Metrics

```kotlin
// app/build.gradle.kts
kotlinOptions {
    freeCompilerArgs += listOf(
        "-P", "plugin:androidx.compose.compiler.plugins.kotlin:reportsDestination=" +
              project.layout.buildDirectory.dir("compose-reports").get().asFile.absolutePath,
        "-P", "plugin:androidx.compose.compiler.plugins.kotlin:metricsDestination=" +
              project.layout.buildDirectory.dir("compose-reports").get().asFile.absolutePath,
    )
}
```

Generates classes/composables stability reports. Identify which classes are unstable and fix.

### Baseline Profiles

Compose apps benefit massively from baseline profiles. Generate with `androidx.benchmark`:

```bash
./gradlew :baselineprofile:generateBaselineProfile
```

Drops cold start time 20-40%.

## Anti-Patterns (Android-specific)

| Anti-pattern | Why it's bad | Correct approach |
|---|---|---|
| `collectAsState()` instead of `collectAsStateWithLifecycle()` | Wastes battery in background | Always use `WithLifecycle` variant |
| `LaunchedEffect(true) { }` or `LaunchedEffect(Unit) { }` everywhere | Runs once but easy to misuse | Use proper key (id, viewModel ref) |
| `var viewModel: ViewModel` field in composable | Lost on recomp | `viewModels()` in Activity, `hiltViewModel()` in composable |
| Heavy work in `init { }` of ViewModel | Blocks UI on creation | Defer to `viewModelScope.launch` |
| Forgetting `enableEdgeToEdge()` + `Modifier.systemBarsPadding()` | UI clipped by system bars | Use `enableEdgeToEdge()` + `WindowInsets.safeDrawing` |
| String-based nav routes | Typo crashes | Use `@Serializable` route classes (2.8+) |
| `mutableStateOf<MyClass>(...)` for unstable types | Compose can't skip recomp | Mark `@Immutable` or use `derivedStateOf` |
| `AndroidView` everywhere instead of pure Compose | Bypasses optimizations | Only for missing widgets (MapView, WebView) |
| `remember { mutableStateOf(...) }` for ViewModel state | Lost on rotation | Hoist to ViewModel + `collectAsState` |
| `LocalContext.current.startActivity(intent)` | Hard to test | Use `rememberLauncherForActivityResult` |
| `BroadcastReceiver` registered in composable without `DisposableEffect` | Leak | Always register/unregister via `DisposableEffect` |

## Testing

```kotlin
// androidTest
class WalletScreenTest {
    @get:Rule val rule = createAndroidComposeRule<MainActivity>()

    @Test fun showsWalletsWhenLoaded() {
        rule.setContent {
            BhodlTheme {
                WalletScreen(viewModel = fakeLoadedViewModel())
            }
        }
        rule.onNodeWithText("Main wallet").assertExists()
        rule.onNodeWithContentDescription("Send").performClick()
    }

    @Test fun navigatesToDetail() {
        // setup with TestNavHostController
    }
}
```

For unit tests of Composables: use **Robolectric** + `createComposeRule()`.
For visual regression: **Paparazzi** (Square) — JVM-based, fast, no emulator needed.
For Android instrumented snapshot: **Roborazzi** — runs on emulator.

## Compose for Wear OS

```kotlin
implementation("androidx.wear.compose:compose-material3:1.5.0")
implementation("androidx.wear.compose:compose-foundation:1.5.0")
implementation("androidx.wear.compose:compose-navigation:1.5.0")
```

```kotlin
@Composable
fun WearApp() {
    MaterialTheme {
        ScalingLazyColumn(
            modifier = Modifier.fillMaxSize(),
        ) {
            item { Chip(label = { Text("Send") }, onClick = { /* ... */ }) }
            item { Chip(label = { Text("Receive") }, onClick = { /* ... */ }) }
        }
    }
}
```

Wear UI uses different components (`Chip`, `ScalingLazyColumn`, `TimeText`) but same Compose paradigm.

## When NOT to Use This Skill

| Scenario | Use Instead |
|----------|-------------|
| Cross-platform UI (Android + iOS + Desktop) | `frontend-frameworks/compose-multiplatform` |
| Pure Kotlin language patterns | `languages/kotlin` |
| Android Keystore, Biometric, NFC, sensors | `mobile/android-native` |
| KMP module setup | `mobile/kotlin-multiplatform` |
| iOS UI work | `mobile/ios-native` |
| Detailed nav patterns | [navigation.md](quick-ref/navigation.md) |
| Activity Result Contracts, AndroidView interop | [interop.md](quick-ref/interop.md) |
Files in this package (4)
  • SKILL.md 18 KB
  • quick-ref/interop.md 10 KB
  • quick-ref/navigation.md 10 KB
  • quick-ref/state-effects.md 8 KB

Versions

RepositoryScoreLicence
This page · claude-dev-suite/claude-dev-suite90MIT
G1Joshi/Agent-Skills100MIT

Database snapshot: 13.11.2026 · package version df0b5aab61d5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100jetpack-compose-expert
    Use when working in a native Android Jetpack Compose project - build.gradle.kts with androidx.compose BOM or org.jetbrains.kotlin.plugin.compose, *.kt files containing @Composable functions, MainActivity with setContent, or mentions of Compose, Material 3, recomposition,…
  • 100android-expert
    Expert in Android development with Jetpack Compose, Material Design, ViewModel, and modern Android architecture. Use when the user mentions mobile, Kotlin, Jetpack Compose, Material Design, or Google, or when the task involves Android Architecture, Android Components, Jetpack…
  • 100android-compose
    Jetpack Compose framework guardrails, patterns, and best practices for AI-assisted development. Use when working with Android Compose projects, or when the user mentions Jetpack Compose. Provides composable patterns, state management, Material 3, navigation, and lifecycle guidelines.
  • 100android-compose
    Modern Android development with Jetpack Compose as the default UI toolkit and Material 3 Expressive as the default design direction, a dated snapshot. Covers Compose fundamentals (composables, modifiers, state hoisting, side effects, lazy lists, strong skipping, recomposition),…
  • 100android-compose
    Build high-performance declarative UI with Jetpack Compose. Use when writing Composable functions, optimizing recomposition, hoisting state, or working with LazyColumn and side effects; defer deep-link and navigation routing to android-navigation.
  • 100kotlin-android
    Use when building or fixing a native Android app in Kotlin and Jetpack Compose on the UDF layered architecture — ViewModel/StateFlow, Hilt, Room, Retrofit, coroutines, type-safe Navigation, and the Gradle/AGP surface. NOT shared Android and iOS UI from one Kotlin codebase (that…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.