A watch face Complication displays data from a data provider. With the Complications API, watch faces can choose the data providers they want to use to get the underlying data. This enables watch faces to display information beyond the time of day without needing code for getting the data.
The Complications API also enables users to select data providers of their choice. Additionally, Wear OS by Google provides a user interface for data source selection.

To add complications to a watch face, do the following:
- Decide how many complication slots you want to include, and what complication types to support in each one.
- Set default data providers for each slot.
- Allow users to choose data providers.
- Set permissions to receive complication data.
- Activate complications to start receiving data.
- Render complications when drawing your watch face.
- Test that complication data is rendered correctly.
Set default providers for watch faces
Watch faces can specify default providers that are used until a user
selects a provider. Set default providers using the
setDefaultComplicationProvider()
method in
WatchFaceService.Engine
. This method may be called at any
time, but it does nothing if the user already chose a provider for the given complication.
For most providers, the RECEIVE_COMPLICATION_DATA
permission
must be granted to a watch face before data can flow to it. However, some
system providers are considered safe because they only supply information that the watch face
already could obtain itself. Safe providers do not require you to send permissions to the
watch face before data is sent (see System providers). These providers may be
preferable to use as defaults, as they can supply data immediately.
Alternatively, if a watch face has a partnership with a certain provider and wishes to use it as a default, it can request that the provider list it as a safe watch face.
System providers
The system includes providers that can be used as defaults.
The setDefaultSystemComplicationProvider()
method, in the
WatchFaceService.Engine
class, sets a default
system provider for a complication. This method takes an ID
(as an integer) that represents a system provider.
The available IDs are listed
in the
SystemProviders
class.
The following table has details about some of the supported system providers:
Method name in the SystemProviders class | Safety | Can be the default | Notes |
---|---|---|---|
dateProvider()
|
Yes | Yes | The standard system date provider. Tapping opens the standard Agenda app. |
currentTimeProvider()
|
Yes | Yes | The standard system "time and date" provider. No tap action. |
batteryProvider()
|
Yes | Yes | The standard system battery provider. No tap action. |
stepCountProvider()
|
Yes | Yes |
Shows a daily total of steps, as reported by
readDailyTotal .
|
unreadCountProvider()
|
Yes | Yes | Shows the number of unread notifications in the stream. |
worldClockProvider()
|
Yes | Yes | Will default to London or New York. Tap to change the time zone. |
appsProvider()
|
Yes | Yes | Will show an "apps" icon at first. Tap to choose an app. |
nextEventProvider()
|
No | Yes (but not a safe provider) | The standard system "next event" provider. Tapping opens the standard Agenda app. |
Allow users to choose data providers
Wear OS provides a user interface (via an Activity) that enables users to choose providers for a particular complication. Watch faces can call the createProviderChooserHelperIntent() method to obtain an intent that can be used to show the chooser interface.
When a watch face calls createProviderChooserHelperIntent
, the watch face
supplies a watch face complication ID and a list of supported types. List the
types in order of preference, usually with types
offering more information, such as ranged value, given higher preference.
When the user selects a data provider, the configuration is saved automatically; nothing more is required from the watch face.
See the Watch Face sample app for the full-featured, recommended code for the settings user interface.
That code includes:
- A standard interface for complication settings.
- Easy access to other settings.
A starting point for reviewing that code is the
AnalogComplicationConfigActivity
class, which has a
getDataToPopulateAdapter()
method that returns a list of the
settings entries available in the UI.
Open the provider chooser
A watch face must have the following permission to receive complication data and open the provider chooser:
com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
A watch face that was not granted the above permission will be unable to start the provider chooser.
To make it easier to request the permission and start the chooser, the
ComplicationHelperActivity
class is available in the wearable support
library. Use this class instead of the
ProviderChooserIntent
class to start the chooser in almost all cases.
Request the necessary permission
To use ComplicationHelperActivity
, add it to the watch face
in the
manifest file:
<activity android:name="android.support.wearable.complications.ComplicationHelperActivity"/>
To start the provider chooser, call the
ComplicationHelperActivity.createProviderChooserHelperIntent
method, to obtain an intent.
Use the new intent with either startActivity
or
startActivityForResult
to launch the chooser.
Here is an example of using the new intent with
startActivityForResult
:
Kotlin
startActivityForResult( ComplicationHelperActivity.createProviderChooserHelperIntent( activity, watchFace, complicationId, ComplicationData.TYPE_LARGE_IMAGE ), PROVIDER_CHOOSER_REQUEST_CODE )
Java
startActivityForResult( ComplicationHelperActivity.createProviderChooserHelperIntent( getActivity(), watchFace, complicationId, ComplicationData.TYPE_LARGE_IMAGE), PROVIDER_CHOOSER_REQUEST_CODE);
When the helper activity is started, the helper activity checks if the permission was granted. If the permission was not granted, the helper activity makes a runtime permission request. If the permission request is accepted (or is unneeded), the provider chooser is shown.
If startActivityForResult
was used with the intent, the
result delivered back to the calling Activity will have a result code of
RESULT_OK
if a provider was successfully set, or a result
code of RESULT_CANCELLED
if no provider was set.
In the case where a provider was set,
ComplicationProviderInfo
class for the chosen provider will be
included in the data intent of the result, as an extra with the key
ProviderChooserIntent#EXTRA_PROVIDER_INFO
.
Receive complication data
To start receiving complication data, a watch face calls
setActiveComplications()
, in the
WatchFaceService.Engine
class, with a list of watch face
complication IDs. A watch face creates these IDs to uniquely identify
slots on the watch face where complications can appear, and passes them
to the createProviderChooserIntent()
method to allow the user to decide which
complication should go in which slot. Complication data is delivered via the onComplicationDataUpdate()
callback.
In general, watch faces need the above permission in order to receive complication data, but there are some exceptions. Specifically, a watch face can only receive data from a provider if one of the following is true:
- The provider is a "safe" system provider.
- The provider and watch face are from the same app.
- The provider lists the watch face as a "safe" watch face.
- The watch face has the permission.
If none of the above is true, then when
ComplicationData
normally would be sent by a provider to a watch face, the system instead
sends data of the type TYPE_NO_PERMISSION
. This type
includes an icon (an exclamation mark) and short text ("--") to allow it
to be rendered as if it were of the short text type or icon type, for
convenience.
When a watch face receives data of TYPE_NO_PERMISSION
, the
watch face should render this appropriately, so the user can see that
action is needed for the complication to work. If possible, a tap on a
complication in this state should launch a permission request. Use the
ComplicationHelperActivity.createPermissionRequestHelperIntent()
to do this,
if the helper activity was added to the watch face app.
If a user accepts the permission request created by the helper activity,
updates are requested for all the active complications on the watch face
automatically, allowing the TYPE_NO_PERMISSION
data to be
replaced by real data.
Render complications
The watch face may render the data as desired as long as the expected fields are represented. For more information on which fields to include, see the Notes column in the table below.
We provide design guidelines for our style, as a suggestion for standard complications, but developers can use their own styles or incorporate the data into the watch face in different ways.
Draw complications
The
ComplicationDrawable
class enables you to render an entire
complication on a canvas.
The class supports all six of the main complication types, and does the following for you:
- Handles all aspects of layout and styling for complications.
- Draws backgrounds, icons, text, etc., within bounds.
- Allows you to set many options. These include, but are not limited to, options for the following: background color, corner shape and radius, border (or lack of a border), text color, and typeface.
- Decodes and caches images.
If you target API level 24, a ComplicationDrawable
object
can be defined in XML as a resource. Alternatively, you can create a
ComplicationDrawable
object programmatically. You use the
draw()
method to draw a complication and set style options
for the interactive and ambient modes.
ComplicationDrawable
will use burn-in safe icons and images
if they have been provided and the device requires them. To enable this,
call the
ComplicationDrawable.setBurnInProtection()
method when the
device properties are received.
For detailed instructions and examples for drawing complications, see
ComplicationDrawable
, which includes sample XML. For a sample
watch face that utilizes this class and includes sample XML, see the
AnalogComplicationWatchFaceService
sample in the Watch Face sample
app.
If you don't use a ComplicationDrawable
object, use
TextRenderer
for the text of a complication.
Render text
The
TextRenderer
class is intended for use in complications, and
eases the drawing of text on a canvas. The class includes these features:
- If seven characters (the maximum in the short text field) do not fit in the bounds at the requested text size, the class shrinks the text until it fits.
- Text can be flowed over a specified number of lines.
- Text can be ellipsized if it does not fit.
- Rendering is adjusted for an always-on screen (ambient mode).
When you
initialize your watch face engine, you can create a
TextRenderer
object and pass in the TextPaint
object
that you want the TextRenderer
object to use.
The TextPaint
object defines the font, text size, color,
and more. You should create a TextRenderer
object for each
field, e.g. one for a text field and one for a title field.
For example code, including for specifying bounds on the text you want to
render, see
TextRenderer
.
Tap on complications
Use the
ComplicationDrawable.onTap()
method to enable your watch
face to pass tap events to complications. This method builds on the functionality
in which a tap on the watch face triggers the
WatchFaceService.Engine.onTapCommand()
method.
You can pass coordinates to a ComplicationDrawable
with an
onTap
call. This will launch the action associated with the
ComplicationDrawable
that contains the tap coordinates. When
the method is called, you will receive a return value of
true if a ComplicationDrawable
launched the associated
action.
Use the
setHighlightDuration()
method to set the duration for a
complication to remain highlighted after the onTap
method is called.
If you are not using ComplicationDrawable
for a
complication, you will need to detect taps and fire the tap action
PendingIntent
yourself. See
Create interactive watch faces to learn how to create watch faces
that respond to user taps.
Complication types
Complication types determine the kinds of data shown in a complication.
For example, the SHORT_TEXT
type is available when the key
data is a short string. In the example of the SHORT_TEXT
type, optional data are an icon and a short title.
Data providers use these complication types differently from the way watch face providers use these types:
- A data provider chooses the types of complication data to supply. For
example, a step count provider might support the
RANGED_VALUE
andSHORT_TEXT
types, whereas a "next meeting" provider might support theSHORT_TEXT
andLONG_TEXT
types. The data provider also chooses which optional fields of those types to include. - A watch face provider chooses how many complication types to support.
For example, a round complication on a watch face might support the
SHORT_TEXT
,ICON
andRANGED_VALUE
types, whereas a gauge on the watch face might support only theRANGED_VALUE
type.
A
ComplicationData
object will always have a single
complication type. Each complication type has required and optional
fields. Generally, a required field represents the primary piece of data;
most types take their name from the required field.
A given type may include different sets of fields. For example,
SHORT_TEXT
may be just a single piece of text, or a title
and text, or an icon and text. A complication that supports a given type
must have the ability to display all the expected variants. However,
you may not need to display some optional fields (see the Notes
column of the table below). For example, the Short title field of the
RANGED_VALUE
type is not required so that, for example,
gauges can be shown without including text.
Examples of Complication Types
The following shows examples of complication types:

Types and fields
The following table describes the types and fields of the
ComplicationData
object.
If a watch face requests a field that is invalid for a complication type,
a default value for the field is returned.
For example, if a watch face tries to access a Long text
field in a SHORT_TEXT
type, the default value for the
Long text
field (null) is returned.
Type | Required fields | Optional fields | Notes |
---|---|---|---|
SHORT_TEXT | Short text |
Icon Burn-in protection icon Short title |
Show exactly one icon or short title if either or both are provided. |
ICON | Icon | Burn-in protection icon | Used when text is not needed. The icon is expected to be single-color, and may be tinted by the watch face. |
RANGED_VALUE |
Value Min value Max value |
Icon Burn-in protection icon Short text Short title |
Optional fields are not guaranteed to be displayed.
If you want to draw your own progress bar, you can use the
setRangedValueProgressHidden() method to hide the progress bar
provided by the
ComplicationDrawable class.
|
LONG_TEXT | Long text |
Long title Icon Burn-in protection icon Small image |
Show the title if it's provided. |
SMALL_IMAGE | Small image |
A small image has one of two styles: photo style or icon
style. Photo style means it should fill the space and can be
cropped; icon style means it should not be cropped and may be padded.
Image variability can result in an unsuitable image for display
in ambient mode on devices with burn-in protection or with low-bit
ambient mode. When burn-in protection or low-bit ambient mode is
enabled, the watch face may use the Burn-in protection small image
as it is safe. Otherwise, since it is hard for a watch
face to determine suitability, an image should not be displayed.
|
|
LARGE_IMAGE | Large image | This image is expected to be large enough to fill the watch face. Image variability can result in an unsuitable image for display in ambient mode on devices with burn-in protection or with low-bit ambient mode. Since it is hard for a watch face to determine suitability for display, a watch face should not display an image in ambient mode if burn-in protection or low-bit ambient is enabled. |
The types in the table below are for empty data and may be sent for any complication slot. These types have no fields and do not need to be included in a list of supported types. These types enable watch faces to differentiate among the following three cases:
- No provider was chosen
- The user has selected "empty" for a slot
- A provider has no data to send
Providers should not send TYPE_EMPTY
in response to
update requests. Providers should send TYPE_NO_DATA
instead.
Details on the complication types for "empty" data are in the following table:
Complication type | Description |
---|---|
TYPE_NOT_CONFIGURED
|
Sent by the system when a complication is activated but the user has
not selected a provider, and no default was set.
Cannot be sent by providers. |
TYPE_EMPTY
|
Sent by the system when a complication is activated and the user has
chosen "empty" instead of a provider, or when the watch face has
chosen no provider, and this type, as the default.
Cannot be sent by providers. |
TYPE_NO_DATA
|
Sent by the system when a complication (that has a provider) is
activated, to clear the complication before actual data is received
from the provider.
Should be sent by providers if they have no actual data to send. |
Use fields for complication data
The fields of a ComplicationData
object have different
functions. For example, a text field contains the primary data while a
title field is descriptive; a step count complication might have a text
field value of "2,543" with a title field value of "steps."
The following table contains descriptions of the fields in a
ComplicationData
object. The fields may or may not be
populated, depending on the complication type.
Field | Description |
---|---|
Short text | Primary text field for small complications. The maximum length of this field should not exceed seven characters (including any time-dependent text). Watch faces are expected to have the ability to render any seven-character string. Strings vary in width, depending on the characters used. A watch face should adjust the text size to allow it to fit in the complication. If the text exceeds seven characters, it may be truncated. |
Icon | A single-color image representing the data or the source of the data. Must be tintable. Vector drawables are recommended for this field. |
Burn-in protection icon |
Field to enable an icon to be displayed in
ambient mode on devices that use burn-in protection. In
ambient mode, watch faces on devices that use
burn-in protection should not display solid blocks of pixels.
The Burn-in protection icon field is optional for any
complication type that includes the icon field.
The Burn-in protection icon field should not
contain any solid blocks of pixels.
The Burn-in protection icon field should be supplied by
providers if their standard icon is unsuitable for burn-in
protection. A watch face rendering in
ambient mode on a device with burn-in protection enabled
should use the Burn-in protection icon field,
if available, instead of
the icon field.
|
Burn-in protection small image |
Field to enable an image to be displayed in
ambient mode on devices that use burn-in protection. In
ambient mode, watch faces on devices that use
burn-in protection should not display solid blocks of pixels.
The Burn-in protection small image field is optional for
any complication type that includes a small image field.
The Burn-in protection small image field should not
contain any solid blocks of pixels.
The Burn-in protection small image field should be supplied
by providers if their standard small image is unsuitable for burn-in
protection. A watch face rendering in
ambient mode on a device with burn-in protection enabled
should use the Burn-in protection small image field,
if available, instead of
the small image field.
|
Short title |
Descriptive field for small complications.
May only be meaningful in combination with the Short
text field.
The maximum length of this field should not exceed seven characters
(including any time-dependent text). Watch faces are expected to have
the ability to render any seven-character string.
Strings vary in width, depending on the characters used.
A watch face should adjust the text size to allow it to fit in the
complication.
If the text exceeds seven characters, it may be truncated.
|
Long text | Primary data field for large, text-based complications. |
Long title | Descriptive field for large, text-based complications. May only be meaningful in combination with Long text. |
Value | A numerical (float) representation of the data. Expected to be depicted relative to the bounds the Min value and Max value fields (but not required to be between those bounds). |
Min value | The lower bound for the range within which Value should be depicted. Only meaningful in combination with Value and Max value. |
Max value | The upper bound for the range within which value should be depicted. Only meaningful in combination with Value and Min value. |
Small image | A small image to represent the data or the source of the data. May be full color. Not expected to fill the entire watch face. |
Large image | An image with sufficient resolution to fill the watch face. May be full color. |
Test complication types
Each complication type has fields, such as text and icons. If your watch face supports a complication type, you need to support all of the valid field combinations.
You can test the way complication data is displayed on a watch face.
Specifically, a
test suite enables you to test the display of the complication types.
Thus, you don't need to write code to test the valid field combinations
for a ComplicationData
object.
The test suite is a data provider, available as a sample, which cycles through the valid field combinations for a given complication type.
To use the test suite:
- Install the test suite APK on a device or emulator.
- Access your watch face and tap its main settings icon.
- Use the settings UI to choose the test suite: WearComplication-ProviderTestSuite
- Choose a complication data type to test.
- Tap your complication to view the variations of the data type.
- Repeatedly tap your complication to verify that all relevant field combinations are properly displayed.
For example, if a complication supports short text, tap your complication to see all the main combinations of fields for short text.
Related resources
Refer to the following related resources: