A complication is any feature in a watch face that is displayed in addition to time. For example, a battery indicator is a complication. The Complications API is for both watch faces and data provider apps.
Refer to the following related resources:
The rest of this document describes data providers, watch faces, and complication types.
Complication data providers
Apps that provide data (such as battery level, weather, or step-count data) to watch faces for complications are called "complication data providers". These data providers supply raw data and are not responsible for controlling how their data is rendered on a watch face. For writing apps that provide data to watch faces, see Expose data to complications.
As shown in the diagram below, Wear OS by Google mediates the flow of data from providers to watch faces.

Complications in watch faces
Watch faces receive data from complication data providers, which allows them to include complications without needing code for getting the underlying data. Watch faces retain control over how the data is rendered, so they can integrate data naturally with their design; see the design patterns for complications.
To learn how to add complications to a watch face, see Adding Complications to a Watch Face.
Complication types
Complication types define what kinds of data can be shown in a complication or supplied by a data provider. For example, the SHORT_TEXT type is used when the data consists primarily of a short string. A ComplicationData object will always have a single complication type that defines required and optional fields. Generally, a required field represents the primary piece of data; most types take their name from the required field.
Data providers use these complication types differently from the watch faces:
- A data provider chooses the types of complication data to supply (including which optional fields, of those types, to supply) and how many different types can be supported. For example, a step count provider might support the RANGED_VALUE and SHORT_TEXT types, whereas a "next meeting" provider might support the SHORT_TEXT and LONG_TEXT types.
- You can choose how many complications to include in your watch face and the complication types to support. For example, a dial complication on a watch face might support the SHORT_TEXT, ICON and RANGED_VALUE types, whereas a gauge on the watch face might support only the RANGED_VALUE type.
To learn more about different complication types and fields supported by each type, see Using and Testing Complication Types.
API summary
Below is a summary of the Complications API. The API is part of the Wearable Support Library; see the Wear API Reference.
-
ComplicationData
- Parcelable (using a Bundle internally); immutable
- Represents all types of complication data
- Includes a Builder for instance creation
-
ComplicationDrawable
- Enables you to render an entire complication on a canvas
-
ComplicationHelperActivity
- Used to request the following permission:
com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
- Used instead of
ProviderChooserIntent
to start the chooser in almost all cases
- Used to request the following permission:
-
ComplicationManager
- A wrapper for the complication manager service, for use by providers
- Allows providers to send complication data to the system
-
ComplicationProviderService
- Extends
Service
and includes callback methods to respond to the complication system - Callback methods are all called on the main thread
- Extends
-
ComplicationText
- Used to supply text-based values in a
ComplicationData
object - Includes options for time-dependent values, whose text value depends on the current time
- Used to supply text-based values in a
-
ProviderChooserIntent
- Non-instantiable utility class that is not commonly used; use
ComplicationHelperActivity
instead
- Non-instantiable utility class that is not commonly used; use
-
ProviderInfoRetriever
- Can be used (by watch face configuration activities) to retrieve the current data provider information (app, provider name, icon) for all complications belonging to a watch face
-
ProviderUpdateRequester
- Can be used by data provider apps to trigger calls to
onComplicationUpdated
in their provider service, to enable the push of updates
- Can be used by data provider apps to trigger calls to
-
SystemProviders
- Lists system providers that are considered "safe", because they only supply information that the watch face already could obtain itself
-
TextRenderer
- Eases the drawing of text on a canvas
Additionally, the WatchFaceService.Engine
class contains the
following methods:
-
setActiveComplications()
- Should be called by the watch face to tell the
ComplicationManager
object what complication slots are available and what types are supported
- Should be called by the watch face to tell the
-
onComplicationDataUpdate()
- Called by the
ComplicationManager
object to send complication data to the watch face
- Called by the
-
setDefaultSystemComplicationProvider()
- Sets a default system provider for a complication.
This method takes an ID (as an integer) for a system provider.
The available IDs are listed in the
SystemProviders
class.
- Sets a default system provider for a complication.
This method takes an ID (as an integer) for a system provider.
The available IDs are listed in the