Quick start

For the best experience developing with Compose, download and install Android Studio. It includes many smart editor features, such as new project templates and the ability to immediately preview your Compose UI and animations.

Get Android Studio

Follow these instructions to create a new Compose app project, set up Compose for an existing app project, or import a sample app written in Compose.

Create a new app with support for Compose

If you want to start a new project that includes support for Compose by default, Android Studio includes various project templates to help you get started. To create a new project that has Compose setup correctly, proceed as follows:

1. If you're in the Welcome to Android Studio window, click Start a new Android Studio project. If you already have an Android Studio project open , select File > New > New Project from the menu bar.
2. In the Select a Project Template window, select Empty Compose Activity and click Next.
3. In the Configure your project window, do the following:
   1. Set the Name, Package name, and Save location as you normally would. Note that, in the Language dropdown menu, Kotlin is the only available option because Jetpack Compose works only with classes written in Kotlin.
   2. In the Minimum API level dropdown menu, select API level 21 or higher.
4. Click Finish.

Now you're ready to start developing an app using Jetpack Compose. To help you get started and learn about what you can do with the toolkit, try the Jetpack Compose tutorial.

Set up Compose for an existing app

To start using Compose, you need to first add some build configurations to your project. Add the following definition to your app’s build.gradle file:

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.3.2"
    }
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.3.2"
    }
}

Some things to note:

• Setting the compose flag to true inside the Android BuildFeatures block enables Compose functionality.
• Kotlin Compiler extension versioning defined in the ComposeOptions block is tied to Kotlin versioning. Make sure to consult the Compatibility map and choose a version of the library that matches your project’s Kotlin version.

In addition, add the Compose BOM and the subset of Compose library dependencies you need to your dependencies from the block below:

dependencies {

    def composeBom = platform('androidx.compose:compose-bom:2022.10.00')
    implementation composeBom
    androidTestImplementation composeBom

    // Choose one of the following:
    // Material Design 3
    implementation 'androidx.compose.material3:material3'
    // or Material Design 2
    implementation 'androidx.compose.material:material'
    // or skip Material Design and build directly on top of foundational components
    implementation 'androidx.compose.foundation:foundation'
    // or only import the main APIs for the underlying toolkit systems,
    // such as input and measurement/layout
    implementation 'androidx.compose.ui:ui'

    // Android Studio Preview support
    implementation 'androidx.compose.ui:ui-tooling-preview'
    debugImplementation 'androidx.compose.ui:ui-tooling'

    // UI Tests
    androidTestImplementation 'androidx.compose.ui:ui-test-junit4'
    debugImplementation 'androidx.compose.ui:ui-test-manifest'

    // Optional - Included automatically by material, only add when you need
    // the icons but not the material library (e.g. when using Material3 or a
    // custom design system based on Foundation)
    implementation 'androidx.compose.material:material-icons-core'
    // Optional - Add full set of material icons
    implementation 'androidx.compose.material:material-icons-extended'
    // Optional - Add window size utils
    implementation 'androidx.compose.material3:material3-window-size-class'

    // Optional - Integration with activities
    implementation 'androidx.activity:activity-compose:1.5.1'
    // Optional - Integration with ViewModels
    implementation 'androidx.lifecycle:lifecycle-viewmodel-compose:2.5.1'
    // Optional - Integration with LiveData
    implementation 'androidx.compose.runtime:runtime-livedata'
    // Optional - Integration with RxJava
    implementation 'androidx.compose.runtime:runtime-rxjava2'

}

dependencies {

    val composeBom = platform("androidx.compose:compose-bom:2022.10.00")
    implementation composeBom
    androidTestImplementation composeBom

    // Choose one of the following:
    // Material Design 3
    implementation("androidx.compose.material3:material3")
    // or Material Design 2
    implementation("androidx.compose.material:material")
    // or skip Material Design and build directly on top of foundational components
    implementation("androidx.compose.foundation:foundation")
    // or only import the main APIs for the underlying toolkit systems,
    // such as input and measurement/layout
    implementation("androidx.compose.ui:ui")

    // Android Studio Preview support
    implementation("androidx.compose.ui:ui-tooling-preview")
    debugImplementation("androidx.compose.ui:ui-tooling")

    // UI Tests
    androidTestImplementation("androidx.compose.ui:ui-test-junit4")
    debugImplementation("androidx.compose.ui:ui-test-manifest")

    // Optional - Included automatically by material, only add when you need
    // the icons but not the material library (e.g. when using Material3 or a
    // custom design system based on Foundation)
    implementation("androidx.compose.material:material-icons-core")
    // Optional - Add full set of material icons
    implementation("androidx.compose.material:material-icons-extended")
    // Optional - Add window size utils
    implementation("androidx.compose.material3:material3-window-size-class")

    // Optional - Integration with activities
    implementation("androidx.activity:activity-compose:1.5.1")
    // Optional - Integration with ViewModels
    implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.5.1")
    // Optional - Integration with LiveData
    implementation("androidx.compose.runtime:runtime-livedata")
    // Optional - Integration with RxJava
    implementation("androidx.compose.runtime:runtime-rxjava2")

}

Try Jetpack Compose sample apps

The fastest way to experiment with the capabilities of Jetpack Compose is by trying Jetpack Compose sample apps hosted on GitHub. To import a sample app project from Android Studio, proceed as follows:

1. If you're in the Welcome to Android Studio window, select Import an Android code sample. If you already have an Android Studio project open, select File > New > Import Sample from the menu bar.
2. In the search bar near the top of the Browse Samples wizard, type "compose".
3. Select one of the Jetpack Compose sample apps from the search results and click Next.
4. Either change the Application name and Project location or keep the default values.
5. Click Finish.

Android Studio downloads the sample app to the path you specified and opens the project. You can then inspect MainActivity.kt in each of the examples to see Jetpack Compose APIs such as crossfade animation, custom components, using typography, and displaying light and dark colors in the in-IDE preview.

To use Jetpack Compose for Wear OS, see Set up Jetpack Compose on Wear OS.

Using the Bill of Materials

The Compose Bill of Materials (BOM) lets you manage all of your Compose library versions by specifying only the BOM’s version. The BOM itself has links to the stable versions of the different Compose libraries, in such a way that they work well together. When using the BOM in your app, you don't need to add any version to the Compose library dependencies themselves. When you update the BOM version, all the libraries that you're using are automatically updated to their new versions.

To find out which Compose library versions are mapped to a specific BOM version, check out the BOM to library version mapping.

Why isn't the Compose Compiler library included in the BOM?

The Compose Kotlin compiler extension (androidx.compose.compiler) is not linked to the Compose library versions. Instead, it is linked to versions of the Kotlin compiler plugin and released in a separate cadence from the rest of Compose, so make sure to use a version that is compatible with your version of Kotlin. You can find the Kotlin version that maps to each version of the plugin at Compose to Kotlin Compatibility Map.

How do I use a different library version than what's designated in the BOM?

In the build.gradle dependencies section, keep the import of the BOM platform. On the library dependency import, specify the desired version. For example, here's how to declare dependencies if you want to use an alpha version of Material 3, no matter what version is designated in the BOM:

dependencies {
    // Import the Compose BOM
    implementation platform('androidx.compose:compose-bom:2022.10.00')

    // Override Material Design 3 library version with a pre-release version
    implementation 'androidx.compose.material3:material3:1.1.0-alpha01'

    // Import other Compose libraries without version numbers
    // ..
    implementation 'androidx.compose.foundation:foundation'
}

Does the BOM automatically add all the Compose libraries to my app?

No. To actually add and use Compose libraries in your app, you must declare each library as a separate dependency line in your module (app-level) Gradle file (usually app/build.gradle).

Using the BOM ensures that the versions of any Compose libraries in your app are compatible, but the BOM doesn't actually add those Compose libraries to your app.

Why is the BOM the recommended way to manage Compose library versions?

Going forward, Compose libraries will be versioned independently, which means version numbers will start to be incremented at their own pace. The latest stable releases of each library are tested and guaranteed to work nicely together. However, finding the latest stable versions of each library can be difficult, and the BOM helps you to automatically use these latest versions.

Am I forced to use the BOM?

No. You can still choose to add each dependency version manually. However, we recommend using the BOM as it will make it easier to use all of the latest stable versions at the same time.

Does the BOM work with version catalogs?

Yes. You can include the BOM itself in the version catalog, and omit the other Compose library versions:

[libraries]
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "androidxComposeBom" }
androidx-compose-foundation = { group = "androidx.compose.foundation", name = "foundation" }

Don’t forget to import the BOM in your module’s build.gradle:

dependencies {
    val composeBom = platform(libs.androidx.compose.bom)
    implementation(composeBom)
    androidTestImplementation(composeBom)

    // import Compose dependencies as usual
}

How do I report an issue or offer feedback on the BOM?

You can file issues on our issue tracker.

BOM to library version mapping