Compose Multiplatform application

You can use this template to start developing your own Compose Multiplatform application targeting desktop, Android, and iOS. Follow our tutorial below to get your first Compose Multiplatform app up and running. The result will be a Kotlin Multiplatform project that uses the Compose Multiplatform UI framework.

Set up the environment

To work with this template, you need the following:

• A machine running a recent version of macOS
• Xcode
• Android Studio
• The Kotlin Multiplatform Mobile plugin
• The CocoaPods dependency manager

Check your environment

Before you start, use the KDoctor tool to ensure that your development environment is configured correctly:

1. Install KDoctor with Homebrew:

   brew install kdoctor
   

2. Run KDoctor in your terminal:

   kdoctor
   

   If everything is set up correctly, you'll see valid output:

   Environment diagnose (to see all details, use -v option):
   [✓] Operation System
   [✓] Java
   [✓] Android Studio
   [✓] Xcode
   [✓] Cocoapods
   
   Conclusion:
     ✓ Your system is ready for Kotlin Multiplatform Mobile development!
   

Otherwise, KDoctor will highlight which parts of your setup still need to be configured and will suggest a way to fix them.

Examine the project structure

Open the project in Android Studio and switch the view from Android to Project to see all the files and targets belonging to the project:

Your Compose Multiplatform project includes 4 modules:

shared

This is a Kotlin module that contains the logic common for desktop, Android, and iOS applications, that is, the code you share between platforms.

This shared module is also where you'll write your Compose Multiplatform code. In shared/src/commonMain/kotlin/App.kt, you can find the shared root @Composable function for your app.

It uses Gradle as the build system. You can add dependencies and change settings in shared/build.gradle.kts. The shared module builds into a Java library, an Android library, and an iOS framework.

desktopApp

This is a Kotlin module that builds into a desktop application. It uses Gradle as the build system. The desktopApp module depends on and uses the shared module as a regular library.

androidApp

This is a Kotlin module that builds into an Android application. It uses Gradle as the build system. The androidApp module depends on and uses the shared module as a regular Android library.

iosApp

This is an Xcode project that builds into an iOS application. It depends on and uses the shared module as a CocoaPods dependency.

Run your application

On desktop

To run your desktop application in Android Studio, select desktopApp in the list of run configurations and click Run:

You can also run Gradle tasks in the terminal:

• ./gradlew run to run application
• ./gradlew package to store native distribution into build/compose/binaries

On Android

To run your application on an Android emulator:

1. Ensure you have an Android virtual device available. Otherwise, create one.

2. In the list of run configurations, select androidApp.

3. Choose your virtual device and click Run:

   
   

   

On iOS

Running on a simulator

To run your application on an iOS simulator in Android Studio, modify the iosApp run configuration:

1. In the list of run configurations, select Edit Configurations:

   

2. Navigate to iOS Application | iosApp.

3. In the Execution target list, select your target device. Click OK:

   

4. The iosApp run configuration is now available. Click Run next to your virtual device:

   

Running on a real iOS device

You can run your Compose Multiplatform application on a real iOS device for free. To do so, you'll need the following:

• The TEAM_ID associated with your Apple ID
• The iOS device registered in Xcode

Finding your Team ID

In the terminal, run kdoctor --team-ids to find your Team ID. KDoctor will list all Team IDs currently configured on your system, for example:

3ABC246XYZ (Max Sample)
ZABCW6SXYZ (SampleTech Inc.)

To run the application, set the TEAM_ID:

1. In the template, navigate to the iosApp/Configuration/Config.xcconfig file.
2. Set your TEAM_ID.
3. Re-open the project in Android Studio. It should show the registered iOS device in the iosApp run configuration.

Make your first changes

You can now make some changes in the code and check that they are visible in both the iOS and Android applications at the same time:

1. In Android Studio, navigate to the shared/src/commonMain/kotlin/App.kt file. This is the common entry point for your Compose Multiplatform app.

   Here, you see the code responsible for rendering the "Hello, World!" button and the animated Compose Multiplatform logo:

   @OptIn(ExperimentalResourceApi::class)
   @Composable
   internal fun App() {
       MaterialTheme {
           var greetingText by remember { mutableStateOf("Hello, World!") }
           var showImage by remember { mutableStateOf(false) }
           Column(Modifier.fillMaxWidth(), horizontalAlignment = Alignment.CenterHorizontally) {
               Button(onClick = {
                   greetingText = "Hello, ${getPlatformName()}"
                   showImage = !showImage
               }) {
                   Text(greetingText)
               }
               AnimatedVisibility(showImage) {
                   Image(
                       painterResource("compose-multiplatform.xml"),
                       null
                   )
               }
           }
       }
   }

2. Update the shared code by adding a text field that will update the name displayed on the button:

   @OptIn(ExperimentalResourceApi::class)
   @Composable
   internal fun App() {
       MaterialTheme {
           var greetingText by remember { mutableStateOf("Hello, World!") }
           var showImage by remember { mutableStateOf(false) }
           Column(Modifier.fillMaxWidth(), horizontalAlignment = Alignment.CenterHorizontally) {
               Button(onClick = {
                   greetingText = "Hello, ${getPlatformName()}"
                   showImage = !showImage
               }) {
                   Text(greetingText)
               }
   +           TextField(greetingText, onValueChange = { greetingText = it })
               AnimatedVisibility(showImage) {
                   Image(
                       painterResource("compose-multiplatform.xml"),
                       null
                   )
               }
           }
       }
   }

3. Re-run the desktopApp, androidApp, and iosApp configurations. You'll see this change reflected in all three apps:

   

How to configure the iOS application

To get a better understanding of this template's setup and learn how to configure the basic properties of your iOS app without Xcode, open the iosApp/Configuration/Config.xcconfig file in Android Studio. The configuration file contains:

• APP_NAME, a target executable and an application bundle name.
• BUNDLE_ID, which uniquely identifies the app throughout the system.
• TEAM_ID, a unique identifier generated by Apple that's assigned to your team.

To configure the APP_NAME option, open Config.xcconfig in any text editor before opening the project in Android Studio, and then set the desired name.

If you need to change this option after you open the project in Android Studio, do the following:

1. Close the project in Android Studio.
2. Run ./cleanup.sh in your terminal.
3. Change the setting.
4. Open the project in Android Studio again.

To configure advanced settings, use Xcode. After opening the project in Android Studio, open the iosApp/iosApp.xcworkspace file in Xcode and make changes there.

Next steps

We encourage you to explore Compose Multiplatform further and try out more projects:

• Create an application targeting iOS and Android with Compose Multiplatform
• Create an application targeting Windows, macOS, and Linux with Compose Multiplatform for Desktop
• Complete more Compose Multiplatform tutorials
• Explore some more advanced Compose Multiplatform example projects