
KMP-ComposeUIViewController
KSP library and Gradle plugin for generating ComposeUIViewController and UIViewControllerRepresentable files when using Compose Multiplatform for iOS.
Compatibility
Motivation
As the project expands, the codebase required naturally grows, which can quickly become cumbersome and susceptible to errors. To mitigate this challenge, this library leverages Kotlin Symbol Processing to automatically generate the necessary Kotlin and Swift code for you.
It can be used for simple and advanced use cases.
Simple
In simple scenarios, the rendering and state management of the @Composable or UIViewController are handled entirely within a single platform
— either in the shared KMP module or directly in the iOS app. It's simply a matter of embedding the component in one platform or the other, with
no cross-platform coordination required.
Advanced
In advanced scenarios, rendering and state management are collaborative between platforms. Certain operations — such as emitting state updates or
embedding a @Composable or UIViewController — can be delegated from one platform to the other. This enables more complex integrations, where
state and UI responsibilities are shared or transferred as needed between the KMP module and the iOS app.
Kotlin Multiplatform and Compose Multiplatform are built upon the philosophy of incremental adoption and sharing only what you require.
Consequently, the support for this specific use-case - in my opinion - is of paramount importance, especially in its capacity to entice iOS developers to embrace Compose Multiplatform.
[!NOTE]
This library takes care of the heavy lifting for you, but if you're interested in understanding how it works, the detailed approach is explained here: Compose Multiplatform — Managing UI State on iOS.
Installation
Configure the plugins block with the following. Once added, you can use the ComposeUiViewController block to set up the plugin's configuration.
plugins {
id("org.jetbrains.kotlin.multiplatform")
id("io.github.guilhe.kmp.plugin-composeuiviewcontroller") version "$LASTEST_VERSION"
}
ComposeUiViewController {
iosAppName = "Gradient"
targetName = "Gradient"
}
With this setup, all necessary configurations are automatically applied. You only need to adjust the ComposeUiViewController block to match your
project settings (e.g. iosAppName and targetName). If you wish to change the default values, check the available parameters.
§
Build output (sample)
When building the project, you should see output similar to this:
> Task :shared:copyFilesToXcode
> Using xcodeproj gem version 1.27.0 (minimum: 1.27.0)
> Starting smart sync process
> KSP output: 4 Swift file(s) found
> New file: GradientScreenSwiftUIViewControllerRepresentable.swift
> New file: GradientScreenMixedAUIViewControllerRepresentable.swift
> New file: GradientScreenMixedBUIViewControllerRepresentable.swift
> New file: GradientScreenComposeUIViewControllerRepresentable.swift
> Summary: 0 unchanged, 4 copied, 0 removed
> Detected changes. Rebuilding Xcode references
> Created new group "Representables"
> Adding: GradientScreenComposeUIViewControllerRepresentable.swift
> Adding: GradientScreenMixedAUIViewControllerRepresentable.swift
> Adding: GradientScreenMixedBUIViewControllerRepresentable.swift
> Adding: GradientScreenSwiftUIViewControllerRepresentable.swift
> Summary: 4 added, 0 removed, 0 unchanged
> Xcodeproj saved successfully
> Done
Swift Export
To enable Swift Export support, just follow the official documentation.
When using dependencies from other modules:
swiftExport {
moduleName = "Shared"
export(projects.otherModule) { ... }
}
Don't forget to import the plugin in each module. Check the sample-swift-export.
[!IMPORTANT]
When switching between modes - embedAndSignAppleFrameworkForXcode to embedSwiftExportForXcode or vice versa - it's recommended to follow this
steps:
- Delete the
Derived Data using Xcode or DevCleaner app;
- Run
./gradlew clean --no-build-cache.
SPM support - experimental
The SPM export mode works with both Swift Export and ObjC Export . It generates a local Swift Package with the generated UIViewControllerRepresentable files, replacing the xcodeproj gem approach. Enable it in the ComposeUiViewController block:
ComposeUiViewController {
iosAppName = "Gradient"
targetName = "Gradient"
experimentalSpmExport = true
}
One-time setup
Run this task once after enabling experimentalSpmExport. It creates the local Swift Package stub and automatically adds the package reference to your Xcode project — no manual Xcode changes needed:
./gradlew :shared:createRepresentablesPackage
After running it, you should see a Swift Package Dependency in your project. The package is empty at this point, but it's ready to be populated with the generated UIViewControllerRepresentable files on every build.
[!NOTE]
This task is idempotent: safe to re-run after ./gradlew clean.
Fresh install
To fully remove the generated SPM package and its Xcode project reference (e.g. to reset and start over), run:
./gradlew :shared:deleteRepresentablesPackage
This will remove the Package containing the Representables. Afterward, run createRepresentablesPackage to set it up again.
Build output (sample)
When building the project, you should see output similar to this:
> Task :shared:exportToSpm
> Arch: iosSimulatorArm64, Config: Debug
> Swift Export: interfaces linked → iosSimulatorArm64/Debug/dd-interfaces
> Package.swift updated
> Starting smart sync process
> KSP output: 4 Swift file(s) found
> New file: GradientScreenSwiftUIViewControllerRepresentable.swift
> New file: GradientScreenMixedAUIViewControllerRepresentable.swift
> New file: GradientScreenMixedBUIViewControllerRepresentable.swift
> New file: GradientScreenComposeUIViewControllerRepresentable.swift
> Summary: 0 unchanged, 4 copied, 0 removed
> Done
Or, when using ObjC Export:
Code generation
KMP module
Inside iosMain we can take advantage of two annotations:
@ComposeUIViewController:
To annotate the @Composable as a desired ComposeUIViewController to be used by the iOS app.
@ComposeUIViewControllerState:
To annotate the parameter as the composable state variable (for advanced use cases).
[!IMPORTANT]
Only 0 or 1 @ComposeUIViewControllerState and an arbitrary number of parameter types (excluding @Composable) are allowed in @ComposeUIViewController functions.
Examples
iOSApp
After a successful build the UIViewControllerRepresentable files are included and referenced in the xcodeproj ready to be used:
import SwiftUI
import Shared
struct SomeView: View {
@State private var state: ViewState = ViewState(isLoading: false)
var body: {
{
()
(viewState: , callback: {})
}
}
}
[!IMPORTANT]
When not using SPM export mode, always delete iosApp/Representables through Xcode.
Sample
For working samples check sample-objc-export, sample-objc-export-spm, sample-swift-export or sample-swift-export-spm.
Open iosApp/Gradient.xcodeproj in Xcode and run standard configuration or use KMP plugin for Android Studio and choose Gradient in run
configurations.
You'll find different use cases:
GradientScreenCompose: A screen rendered entirely in Compose (UI+state) and embedded in iOS;
GradientScreenMixedA: A screen rendered entirely in Compose with its state controlled by iOS;
GradientScreenMixedB: A screen rendered in Compose with a SwiftUI View embedded in it, and the state controlled by iOS;
GradientScreenSwift: A screen rendered entirely in Swift (UI+state) and embedded in Compose.
You can also find other working samples in:

LICENSE
Copyright (c) 2023-present GuilhE
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy
of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under
the License.