Wear Watchface

Create applications for Wear OS by Google smartwatches.
Latest Update Current Stable Release Next Release Candidate Beta Release Alpha Release
December 1, 2021 1.0.0 - - -

Declaring dependencies

To add a dependency on Wear, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:


dependencies {
    // Use to implement wear watchfaces
    implementation "androidx.wear.watchface:watchface:1.0.0"

    // Use to implement wear watchface complications
    implementation "androidx.wear.watchface:watchface-complications-data-source:1.0.0"
    // (Kotlin-specific extensions)
    implementation "androidx.wear.watchface:watchface-complications-data-source-ktx:1.0.0"

    // Use to implement a watchface style and complication editor
    implementation "androidx.wear.watchface:watchface-editor:1.0.0"


dependencies {
    // Use to implement wear watchfaces

    // Use to implement wear watchface complications
    implementation "androidx.wear.watchface:watchface-complications-data-source:1.0.0"
    // (Kotlin-specific extensions)
    implementation "androidx.wear.watchface:watchface-complications-data-source-ktx:1.0.0"

    // Use to implement a watchface style and complication editor

For more information about dependencies, see Add build dependencies.


Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.0

Version 1.0.0

December 1, 2021

androidx.wear.watchface:watchface-*:1.0.0 is released. Version 1.0.0 contains these commits.

** Major Features of 1.0.0 **

The androidx.wear.watchface package is the new recommended library for developing WearOS watch faces. It has a number of new features over the old Wearable Support Library.

  • User styling (e.g. to change the color palette, the style of the watch hands, the look of the hour marks etc) is directly supported by the library (see androidx.wear.watchface.style). It’s now much easier to develop an on watch face editor using androidx.wear.watchface.editor and your watch face can be edited from the system companion app without you needing to write any extra code.
  • Best practices baked in. The library automatically generated screen reader content labels for complications (you can also add your own ones), and the framerate automatically drops when the battery is low and not charging to improve battery life.
  • Less code is needed to develop a watch face, especially for complications where a lot of the boilerplate has moved into the library.

Bug Fixes

  • Fix EditorSession.userStyle.compareAndSet (I6f676)
  • Fix very short watch face delays (Iffb97)
  • Dispatch InteractiveWatchFaceImpl.onDestroy on the UI thread (I83340)
  • Fix several problems with broadcast receivers (I7d25f)

Version 1.0.0-rc01

November 3, 2021

androidx.wear.watchface:watchface-*:1.0.0-rc01 is released. Version 1.0.0-rc01 contains these commits.

Bug Fixes

  • Fix dump() (called by adb shell dumpsys) which got broken by flow migrations. (087cf9e)

  • Ensure proper ordering of writeDirectBootPrefs. We want writeDirectBootPrefs to always run after initStyleAndComplications or we risk delaying UI thread init.(37650ac)

  • Ensure Renderer.onDestroy is called. In the scenario where the renderer has been created but WF init has not completed and Engine.onDestroy is called, we need to call Renderer.onDestroy. (f9952dc)

  • Optimization/fix to isBatteryLowAndNotCharging. This patch moves the initial setup of isBatteryLowAndNotCharging earlier which means it can be done in parallel with createWatchFace. In addition we now listen to ACTION_POWER_DISCONNECTED. (ddffd80

  • InteractiveWatchFaceClientImpl.isConnectionAlive to be false after close (ab9774e)

Version 1.0.0-beta01

October 27, 2021

androidx.wear.watchface:watchface-*:1.0.0-beta01 is released. Version 1.0.0-beta01 contains these commits.

Version 1.0.0-alpha24

October 13, 2021

androidx.wear.watchface:watchface-*:1.0.0-alpha24 is released. Version 1.0.0-alpha24 contains these commits.

API Changes

  • Classes in package androidx.wear.watchface.complications have been moved into a new wear:watchface:watchface-complications project. Note this means you can't include this library as well as any previous alpha version of wear:watchface:watchface-complications-data because you'll get errors about duplicate classes. (I97195)
  • Renderer.dump has been renamed to Renderer.onDump and has been annotated with @UiThread. (I44845)
  • InteractiveWatchFaceClient.addWatchFaceReadyListener has been renamed to addOnWatchFaceReadyListener and removeWatchFaceReadyListener has been renamed to removeOnWatchFaceReadyListener. (I48fea)
  • EditorSession getComplicationsPreviewData and getComplicationsDataSourceInfo are no longer suspend functions, instead they are StateFlow<> properties whose value is initially null. In ListenableEditorSession getListenableComplicationPreviewData and getListenableComplicationsProviderInfo have been removed in favor of the new StateFlow<> objects from the base class. If you need to listen to changes in java code, consider using androidx.lifecycle.FlowLiveDataConversions.asLiveData to convert to LiveData<>. (Ic5483)

Version 1.0.0-alpha23

September 29, 2021

androidx.wear.watchface:watchface-*:1.0.0-alpha23 is released. Version 1.0.0-alpha23 contains these commits.

New Features

The watchface library is now a single library group, and as a result the libraries have moved and you will need to update your gradle imports as follows:

Old New
androidx.wear:wear-complications-data androidx.wear.watchface:watchface-complications-data
androidx.wear:wear-complications-data-source androidx.wear.watchface:watchface-complications-data-source
androidx.wear:wear-watchface androidx.wear.watchface:watchface
androidx.wear:wear-watchface-complications-rendering androidx.wear.watchface:watchface-complications-rendering
androidx.wear:wear-watchface-client androidx.wear.watchface:watchface-client
androidx.wear:wear-watchface-client-guava androidx.wear.watchface:watchface-client-guava
androidx.wear:wear-watchface-data androidx.wear.watchface:watchface-data
androidx.wear:wear-watchface-editor androidx.wear.watchface:watchface-editor
androidx.wear:wear-watchface-editor-guava androidx.wear.watchface:watchface-editor-guava
androidx.wear:wear-watchface-guava androidx.wear.watchface:watchface-guava
androidx.wear:wear-watchface-style androidx.wear.watchface:watchface-style

API Changes

  • Migrate the separate androidx.wear Watchface and complications libraries into androidx.wear.watchface library group. (b25f3c0)
  • Added EditorRequest.canWatchFaceSupportHeadlessEditing to let a client know if a watchface editor supports headless editing. Note there will be some false negatives with this because support was added in asop/1756809 however it will return the correct value for all future watchfaces. (ca55590)
  • Renderer now has a dump() method which can be overridden to add custom data to the information generated by ABD shell dumpsys activity service WatchFaceService. (95235f9)
  • InteractiveWatchFaceClient.addWatchFaceReadyListener now specifies the executor first. (563ac2f)
  • StateFlowCompatHelper has been removed. asLiveData (androidx.lifecycle.asLiveData) should be used instead. (bd35d3)
  • CurrentUserStyleRepository.userStyle is no longer mutable. (I44889)
  • WatchFaceReadyListener has been renamed to OnWatchFaceReadyListener. (Ic12a9)

Bug Fixes

  • InteractiveInstanceManager.deleteInstance to call onDestroy This is needed to ensure InteractiveWatchFaceImpl gets garbage collected.(fce4af8, b/199485839)