Compose Multiplatform on iOS: UIKit and SwiftUI Interop

Interop on iOS is asymmetric. Compose can only enter native UI as a UIViewController (that is what ComposeUIViewController returns), and native UI can only enter Compose through a UIView (UIKitView) or a UIViewController (UIKitViewController). SwiftUI is never embedded directly: it always passes through UIViewControllerRepresentable in one direction and UIHostingController in the other. The four shapes below cover nearly every app.

See Kotlin docs — Integration with the SwiftUI framework and Kotlin docs — Integration with the UIKit framework.

ComposeUIViewController is a function in the androidx.compose.ui.window package (CMP, iosMain) that takes a composable lambda and returns a UIViewController whose view is a Compose surface. Because it is an ordinary view controller, anything that can host one can host Compose. The TrailMate entry point is a one-liner in the shared UI module’s iOS source set.

See Kotlin docs — Integration with the SwiftUI framework.

The Swift name is generated from the Kotlin file and function: a top-level function in MainViewController.kt appears as MainViewControllerKt.MainViewController() under the Objective-C header (the exact spelling is explained on Objective-C Interop, Swift Export and SKIE). The framework baseName — ComposeApp for the wizard template, Shared in earlier TrailMate pages — is the module you import. Renaming the Kotlin file silently renames the Swift symbol, which is the most common cause of "cannot find MainViewControllerKt in scope" after a refactor.

The reverse direction is UIKitView (a single UIView) and UIKitViewController (a UIViewController, needed for SwiftUI and for views that rely on view-controller lifecycle). Both live in iosMain because they reference platform.UIKit types; common code reaches them through an expect composable or a callback parameter.

Both take factory (create once), update (called when observed Compose state read inside it changes), modifier (Compose decides the size — native views have no intrinsic size here, so give them size, fillMaxWidth or height), and optional onReset/onRelease for pooling and cleanup.

A native view inside a Compose scroll container immediately raises a conflict: when the finger lands on the map, did the user want to pan the map or scroll the list? Compose and UIKit use different gesture systems, so CMP defines the policy explicitly.

The consequence of cooperative mode is observable: a quick swipe over a map inside a LazyColumn scrolls the list, while a press-and-hold then drag pans the map. For a full-screen map with no scrollable parent that delay is pure latency, so use non-cooperative mode.

See Kotlin docs — Handling touch events with interop on iOS.

For complex gestures inside an interop view, attach UIGestureRecognizer subclasses natively; they can also cancel the Compose touch sequence. Because UIKitInteropProperties is Experimental, expect the shape to change: the documentation says the long-term intent is a single boolean for interactability, with the mode derived automatically.

Compose draws with Skia (via Skiko) on a Metal-backed CAMetalLayer, so the iOS system sees one opaque layer; the accessibility tree is synthesized from Compose semantics (below). Since CMP 1.11 concurrent rendering (render tasks off the main thread) is enabled by default, and 1.12 improved lazy-layout scrolling on iOS. Two practical frame-rate points follow.

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

Profiling is the same as for any iOS app: Instruments' Time Profiler and Core Animation templates on the iosApp target, described on Performance and Instruments. Kotlin/Native specifics (memory manager, symbolication) are on Kotlin/Native Memory, Performance and Debugging.

Compose’s TextField historically implemented text editing in Compose and only approximated iOS behaviour. CMP added a native text input implementation that uses a real UIView conforming to UITextInput and UIKeyInput, so caret movement, selection, marked text for CJK input, autocorrection, dictation and the magnifier behave like UIKit. It was introduced in CMP 1.11 and is Experimental; it also pairs with the new context menu API. Verify the opt-in in Kotlin docs — What’s new in Compose Multiplatform 1.11.0 before adopting it, because experimental flags move between releases.

CMP maps the Compose semantics tree to native accessibility objects, so VoiceOver, Switch Control, Voice Control and XCTest can use a Compose screen like a native one. Material widgets need no extra work; your own composables should set Modifier.semantics, contentDescription and roles. Modifier.testTag("trailList") surfaces as the native accessibilityIdentifier, which is how XCUITest locates Compose elements — see UI Tests, Test Plans and Coverage.

Increase Contrast is detected in Swift with UIAccessibility.isDarkerSystemColorsEnabled (and the matching status-change notification) and forwarded to the shared theme through a callback. Further accessibility topics (semantics merging, large-text scaling) are shared with the other platforms on Layouts, Material 3, Adaptive UI, Popups and Accessibility, and the native side is on Accessibility.

iOS 26 gives TabView, NavigationStack and toolbars the Liquid Glass look automatically, but only when they are native. A Compose-drawn tab bar can imitate it, never match it. JetBrains' tutorial therefore recommends moving chrome to SwiftUI and keeping content in Compose: a native TabView containing a NavigationStack per tab, where every root and pushed screen is a Compose view controller (shape D in the figure). It requires Xcode 26 and the iOS 26 SDK; the design system itself is on Liquid Glass, Materials and Icons.

The division of labour is explicit.

On the Kotlin side, the iOS entry point exposes one factory per screen and a navigation callback, and routes carry their own title so Swift never calls back into Kotlin to render a bar.

See Kotlin docs — Liquid Glass in a Compose Multiplatform app.

The Swift file illustrates the pattern rather than a literal copy of the tutorial; the tutorial implements the Kotlin half with Navigation 3 and shows how to intercept routes. The reasoning is worth keeping: back gestures, swipe-to-pop, large titles and the collapsing tab bar are things only native containers get exactly right, while the screens — where the shared-code payoff is — stay in Compose. The same Navigation libraries on the Compose side are covered on Lifecycle, ViewModel and Navigation in Compose Multiplatform.

The strongest property of this interop is that it lets you adopt Compose without a rewrite. A common path for a native iOS app that already consumes a shared logic module follows.

TrailMate Everywhere ships both a SwiftUI TrailListView over the shared ViewModel and a CMP MainViewController version in iosApp; switching is a one-line change in its @main struct. The strategic comparison of native UI versus shared UI is on What Is Kotlin Multiplatform? and the iOS integration mechanics on Integrating Shared Code into iOS.

The iOS migration guide lists the breaking changes since 1.7.0 that matter to existing interop code. These are the ones that bite real apps.

See Kotlin docs — iOS migration guides.

The remember { UIView() } row is the subtle one: factory and onReset are alternatives, so a non-null onReset makes Compose reuse a view that is no longer the remembered instance.