Compose Multiplatform Fundamentals

Jetpack Compose is Google’s toolkit for Android. Compose Multiplatform builds on code and releases published by Google: JetBrains takes each Jetpack Compose release as the base of the next CMP release, adds the platform support for iOS, desktop and web, stabilizes it, and ships. The two are developed in close collaboration, but they are separate products with separate artifacts and release dates.

The practical consequence: you can learn Compose from almost any Jetpack Compose material — Google’s official documentation included — and apply it to commonMain. The differences are the platform edges, which is what this page maps. See the Android section’s Compose Layouts, Lists and Modifiers and Compose Material 3 and Theming for the shared vocabulary.

Reading the figure from the top:

On Android, a CMP build pulls Google’s published artifacts; on every other target it pulls JetBrains' builds. You do not choose between them — the Gradle metadata of each CMP artifact maps androidx coordinates for the Android target. The CMP version is not the Kotlin version and not the Jetpack Compose version, though they correspond:

The 1.12.1 release publishes the following artifact families. Note that material3 and the navigation and lifecycle libraries are versioned separately from the core Compose libraries, following Google’s own versioning of those libraries:

Check the exact versions on the release page before pinning them; they move with every CMP release. Material 3, lifecycle and navigation each get a page of their own: Lifecycle, ViewModel and Navigation in Compose Multiplatform and Layouts, Material 3, Adaptive UI, Popups and Accessibility.

Two rules of thumb keep versions sane:

See Kotlin docs — Compatibility and versions and Kotlin docs — What’s new in Compose Multiplatform 1.12.1.

CMP supports only 64-bit platforms. The minimum versions for CMP 1.12.1 and the stability level of each target:

"Beta" for web is a statement about API and behaviour stability, not about whether it runs: expect rough edges (font loading, accessibility, bundle size) and rely on the compatibility build described in the web page when you must support browsers without WasmGC. The matching Kotlin-side tiers are explained in How KMP Compiles: Targets and Tiers.

See Kotlin docs — Compatibility and versions.

A Compose module needs three things: the Kotlin Multiplatform plugin, the Compose compiler plugin and the CMP Gradle plugin. The first two follow the Kotlin version; the CMP plugin follows the CMP version. Declare them once in the version catalog:

See Kotlin docs — Updating Compose compiler.

Note that compose-compiler uses version.ref = "kotlin": that is the whole point of the compiler living in the Kotlin repository. Then apply them to every module that contains @Composable code — here sharedUI — and declare the libraries by direct coordinates:

See Kotlin docs — Create a Kotlin Multiplatform app and Android Developers — Set up the Android Gradle library plugin for KMP.

The module uses com.android.kotlin.multiplatform.library, so there is no androidTarget() call and no Android application in this module: MainActivity lives in androidApp, as explained in The Android Target and AGP 9. The matching catalog entries are plain library aliases:

See Kotlin docs — What’s new in Compose Multiplatform 1.12.1.

The <material3-version-from-release-notes> placeholder is deliberate: Material 3 is versioned independently, and a stale hard-coded value is a common source of "unresolved reference" errors after a CMP upgrade. The project layout around this module (which modules exist, who depends on whom) is described in Project Structure, Targets, Source Sets and the Hierarchy Template.

The Compose compiler is what turns annotated functions into a recomposable tree. Since Kotlin 2.0.0 it is merged into the Kotlin repository and released together with Kotlin, so there is no longer a separate "compiler version vs Kotlin version" compatibility table — the artifact is the Gradle plugin org.jetbrains.kotlin.plugin.compose, versioned identically to Kotlin. Apply it in every module that contains composables, next to org.jetbrains.compose. When used with AGP, it overrides the compiler coordinates AGP would otherwise supply.

Compiler options live in the composeCompiler \{} extension. Reports are the most useful ones: they show which composables the compiler considers restartable and skippable, and which types it considers unstable.

See Kotlin docs — Updating Compose compiler.

Why this matters more in multiplatform than on Android only: a type from a library compiled without the Compose compiler is "unstable" by default, and a composable that takes it is re-run on every parent recomposition. The stability configuration file (one class pattern per line, for example com.example.trailmate.domain. and kotlinx.datetime.) is the supported way to opt such types in without wrapping them. Reading and acting on the reports is covered in the Android section’s Debugging, Code Quality and Performance.

Two Kotlin 2.0 era issues are worth knowing by name, because they show up in old posts. Compose compiler 2.0.0 sometimes inferred stability incorrectly on non-JVM targets, which caused needless or endless recompositions; the fix is Kotlin 2.0.10 or later and dependencies built with the same compiler. Switching a project between Kotlin 1.9 and 2.0 can also trigger MissingResourceException: Missing resource with path until all build/ directories are deleted.

Older CMP projects declared UI dependencies through accessors generated by the Gradle plugin: compose.runtime, compose.ui, compose.foundation, compose.material3, compose.components.resources. Those accessors are deprecated; modern projects, including the wizard-generated ones, depend on the artifact coordinates directly, usually through the version catalog as above.

Why the change: the accessors forced every dependency to the plugin’s own version, while Material 3, navigation and lifecycle now follow independent version lines. Direct coordinates let the version catalog (and Gradle’s dependency management) own all versions, and they make the dependency list readable by any Gradle tool. A project that still uses compose.* builds with deprecation warnings; migrate them when you touch the build.

See Kotlin docs — Create a Kotlin Multiplatform app.

With the module wired, the UI is plain Compose in commonMain. TrailMate’s root composable takes only what it needs (no platform types) and delegates to a theme and a screen:

See Kotlin docs — Layout basics.

App() hands the screen to TrailListScreen, a plain composable in the same package that collects the shared ViewModel’s StateFlow<TrailListUiState> and renders a LazyColumn. Every Compose import in such code comes from androidx.compose. packages — *the package names are the same as in Jetpack Compose, even though on iOS, desktop and web the artifacts are JetBrains builds. That is what makes code written for Android compile unchanged. safeContentPadding() matters on iOS: it keeps content out of the notch and the home-indicator area, which Android draws edge to edge by default. ViewModel creation (koinViewModel()) is covered in Dependency Injection with Koin and Metro and Architecture and Shared ViewModels.

The shared App() is never the program’s entry point. Every platform has its own bootstrap, and these thin entry points are where platform-specific wiring (dependency injection, edge-to-edge, window size) belongs. In a well-structured project they are the only files that differ.

Previews render a composable in the IDE (IntelliJ IDEA and Android Studio) without launching an emulator. They are a core Jetpack Compose feature, and CMP now uses the same annotation: since CMP 1.10.0 the androidx.compose.ui.tooling.preview.Preview annotation is multiplatform. The earlier JetBrains-specific annotation (org.jetbrains.compose.ui.tooling.preview.Preview) is deprecated; use the androidx one in new code. Previews need an Android target, because the rendering is done by the Android tooling.

See Kotlin docs — Compose UI previews.

With AGP 9’s Android-KMP library plugin the tooling dependency goes into androidRuntimeClasspath, as in the snippet (if your IDE’s Gradle accessors do not generate it, write it as "androidRuntimeClasspath"(…​)); with com.android.application — for example in androidApp — the traditional debugImplementation is used instead. A preview is an ordinary composable annotated with @Preview, like App() above.

The supported @Preview parameters in common code are name, group, widthDp, heightDp, locale, showBackground and backgroundColor; the Android-only ones (device frames, UI mode) are Android tooling features. The Jetpack Compose side of previews is in Android Developers — Preview your UI with composable previews.

Previews show isolated composables with fake data. Compose Hot Reload instead applies your code changes to a running app, without restarting it and with its state preserved. It works on the desktop JVM target; there is no hot reload on iOS, Android-via-CMP or web, so the desktop app is your fast UI sandbox for common code, and you verify on the real platforms afterwards.

See Kotlin docs — Compose Hot Reload.

The comparison of the three feedback loops:

Jetpack Compose documentation and community samples are written for Android. If you paste a snippet into commonMain and the IDE reports an unresolved reference, it is almost always an Android-only API. There are three categories:

A few items in the "not yet ported" category exist even without android classes in their signatures, such as Modifier.imeNestedScroll(), Modifier.systemGestureExclusion(), Modifier.magnifier(), LocalOverscrollConfiguration and AnimatedImageVector.animatedVectorResource. The documentation lists them per release; re-check the list after every upgrade, because items move out of it.

When a platform capability is genuinely needed, do not leak the Android type into common code. Define an interface or an expect declaration and provide the platform parts in platform source sets — the mechanism is explained in Expect/Actual and Platform APIs:

See Kotlin docs — Expected and actual declarations.

See Kotlin docs — Android-only components.

The composable’s signature is common; each platform fills in its own implementation. The desktop and web source sets would provide actual`s too (a desktop clipboard copy, the browser share API), or the function can return a no-op. The alternative is a plain interface supplied by Koin from each entry point; choose `expect when the implementation needs @Composable context such as LocalContext.

CMP aims for the same behaviour everywhere, but a handful of differences are unavoidable. They are not bugs; plan for them and test on each platform:

See Kotlin docs — Default UI behavior on different platforms.

The rendering choice is also the source of the biggest non-difference: because every Skia target draws its own pixels, the UI looks identical on iOS and desktop — it does not adopt iOS or macOS system controls. A Switch on iOS is Material’s switch, not a UISwitch. If you need genuinely native look and feel, either use native UI with shared logic (see What Is Kotlin Multiplatform) or embed native views, as TrailMate does for the map.