Watch face complications

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 source apps.

The rest of this document describes data sources, watch faces, and complication types.

Complication data source

Apps that provide data (such as battery level, weather, or step-count data) to watch faces for complications are called complication data sources. These data sources 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 following diagram, Wear OS by Google mediates the flow of data from sources to watch faces.

Complications data flow

Complications in watch faces

Watch faces receive data from complication data sources, 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. For more information, see the design guide on Complications.

To learn how to add complications to a watch face, see Add 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 source. For example, use the SHORT_TEXT type when the data consists primarily of a short string. A ComplicationData object always has a single complication type that defines required and optional fields. A required field represents the primary piece of data; most types take their name from the required field.

Data sources use these complication types differently from the watch faces:

  • A data source 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 source might support the RANGED_VALUE and SHORT_TEXT types, and a next meeting source 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, and 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 Complication types.