Use Jetpack Compose on Wear OS

Compose for Wear OS is similar to Compose for mobile. However, there are some key differences. This guide walks you through the similarities and differences.

Compose for Wear OS is part of Android Jetpack, and just like the other Wear Jetpack libraries you use, it helps you write better code faster.

If you are unfamiliar with using Jetpack Compose for mobile, check out the Compose pathway. Many of the development principles for mobile Compose apply to Compose for Wear OS. To learn more about Compose for Wear OS, see the Compose for Wear OS Pathway and the Wear OS samples repository. on GitHub.

Compatibility

Compose for Wear OS works on watches that support Wear OS 3.0 (API Level 30) and watches that use Wear OS 2.0 (API level 25 and above).

Surfaces

Compose for Wear OS is meant for the overlay surface, which is similar to the app surface on mobile. For more information, see Overlays.

This surface is well suited for complex interactions.

Setting up

Using Jetpack Compose with Wear OS is similar to using Jetpack Compose for any other Android project. The main difference is that Jetpack Compose for Wear adds Wear-specific libraries that make it easier to create user interfaces tailored to watches. In some cases those components share the same name as their non-wear counterparts, such as androidx.wear.compose.material.Button and androidx.compose.material.Button.

Create a new app in Android Studio

To create a new project that includes Jetpack Compose, 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 > Import Sample from the menu bar.
  2. Search for Compose for Wear and select Compose for Wear OS Starter.
  3. In the Configure your project window, do the following:
    1. Set the Application name.
    2. Choose the Project location for your sample.
  4. Click Finish.
  5. Verify that the project's build.gradle file is configured correctly, as described in Gradle properties files.

Now you're ready to start developing an app using Compose for Wear OS.

Jetpack Compose toolkit dependencies

To use Jetpack Compose with Wear OS, you’ll need to include Jetpack Compose toolkit dependencies in your app’s build.gradle file, as shown in the following snippet:

Kotlin

dependencies {
    // General compose dependencies
    implementation "androidx.activity:activity-compose:1.3.1"
    implementation "androidx.compose.ui:ui-tooling-preview:1.0.3"
    // Other compose dependencies

    // Compose for Wear OS Dependencies
    implementation "androidx.wear.compose:compose-material:1.0.0-rc02"

    // Foundation is additive, so you can use the mobile version in your Wear OS app.
    implementation "androidx.wear.compose:compose-foundation:1.0.0-rc02"

    // If you are using Compose Navigation, use the Wear OS version (NOT THE MOBILE VERSION).
    // Uncomment the line below and update the version number.
    // implementation "androidx.wear.compose:compose-navigation:1.0.0-rc02"

    // Testing
    testImplementation "junit:junit:4.13.2"
    androidTestImplementation "androidx.test.ext:junit:1.1.3"
    androidTestImplementation "androidx.test.espresso:espresso-core:3.4.0"
    androidTestImplementation "androidx.compose.ui:ui-test-junit4:1.0.3"
    debugImplementation "androidx.compose.ui:ui-tooling:1.0.3"
}

What is different

Use the WearComposeMaterial version of APIs where possible. While it's technically possible to use the mobile version of Compose Material, it is not optimized for the unique requirements of Wear OS. In addition, mixing Compose Material with Compose Material for Wear OS can result in unexpected behavior. For example, because each library has its own MaterialTheme class, there's the possibility of colors, typography, or shapes being inconsistent if both versions are used.

The following table outlines the dependency differences between Wear OS and Mobile:

Wear OS Dependency

(androidx.wear.*)

Comparison Mobile Dependency

(androidx.*)

androidx.wear.compose:compose-material instead of androidx.compose.material:material1
androidx.wear.compose:compose-navigation instead of androidx.navigation:navigation-compose
androidx.wear.compose:compose-foundation in addition to androidx.compose.foundation:foundation

Here's an example build.gradle file:

// Example project in app/build.gradle file
dependencies {
    // Standard Compose dependencies...

    // Wear specific Compose Dependencies
    implementation "androidx.wear.compose:compose-material:$rootProject.wearVersion"
    implementation "androidx.wear.compose:compose-foundation:$rootProject.wearVersion"

    // For navigation within your app...
    implementation "androidx.wear.compose:compose-navigation:$rootProject.wearVersion"

    // Other dependencies...
}

Feedback

Try out Compose for Wear OS and let us know what you think using the issue tracker or join the #compose-wear channel on Kotlin Slack and let us know there.