Get started with widgets

Prerequisites and Setup

Before you begin, ensure your environment meets the following requirements.

Runtime Requirements

Wear Widgets require version 1.6.1 or higher of the com.google.android.wearable.protolayout.renderer APK on the target device.

Get a compatible version of the renderer in one of the following ways:

• Wear OS 7 Emulator: Use the Wear OS 7 emulator image. Versions lower than 7 are not suitable. For setup instructions, see Set up the Wear OS 7 emulator.
• Physical Device: Use a physical Wear OS device that receives automatic updates from the Google Play Store, or a developer device signed in to the Google Play Store.

To check what version you have installed on your device, use the following command:

adb shell dumpsys package com.google.android.wearable.protolayout.renderer | \
  grep -m 1 versionName | \
  awk -F= '{print $2}'

Gradle Configuration

Wear Widget libraries are available on Google Maven.

1. Configure SDK Version

Ensure your compileSdk and targetSdk are set to 37 or higher.

android {
    compileSdk = 37
    // ...
    defaultConfig {
        targetSdk = 37
        // ...
    }
}

2. Add Dependencies

Include the following dependencies in your app's build.gradle.kts file:

dependencies {
    // Core Wear Widget and Remote Compose libraries
    implementation "androidx.compose.remote:remote-creation-compose:1.0.0-alpha17"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha17"
    implementation "androidx.glance.wear:wear:1.0.0-alpha16"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha16"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha09"

    // Tooling for previews (optional, but recommended)
    implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha17"
    implementation "androidx.wear.compose:compose-ui-tooling:1.6.2"
    implementation "androidx.wear.tiles:tiles-tooling-preview:1.6.2"
    debugImplementation "androidx.wear.tiles:tiles-renderer:1.6.2"
}

dependencies {
    // Core Wear Widget and Remote Compose libraries
    implementation("androidx.compose.remote:remote-creation-compose:1.0.0-alpha17")
    implementation("androidx.compose.remote:remote-core:1.0.0-alpha17")
    implementation("androidx.glance.wear:wear:1.0.0-alpha16")
    implementation("androidx.glance.wear:wear-core:1.0.0-alpha16")
    implementation("androidx.wear.compose.remote:remote-material3:1.0.0-alpha09")

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha17")
    implementation("androidx.wear.compose:compose-ui-tooling:1.6.2")
    implementation("androidx.wear.tiles:tiles-tooling-preview:1.6.2")
    debugImplementation("androidx.wear.tiles:tiles-renderer:1.6.2")
}

Build a Hello World Widget

A Wear Widget consists of a service extending GlanceWearWidgetService and a widget class extending GlanceWearWidget. You define the UI using @RemoteComposable functions.

Define the Service

The service is the entry point that the system binds to.

To define your widget, create a service that extends GlanceWearWidgetService.

@AssociateWithGlanceWearWidget(HelloWidget::class)
class HelloWidgetService : GlanceWearWidgetService() {
    override val widget: GlanceWearWidget = HelloWidget()
}
GetStarted.kt

Define the Widget

The widget class provides the data and layout for the widget.

class HelloWidget : GlanceWearWidget() {
    override suspend fun provideWidgetData(
        context: Context,
        params: WearWidgetParams,
    ): WearWidgetData {
        return WearWidgetDocument(
            background = WearWidgetBrush.color(Color.Blue.rc),
        ) {
            HelloWidgetContent()
        }
    }
}
GetStarted.kt

Define the Content

The content is built using Remote Compose components.

@RemoteComposable
@Composable
fun HelloWidgetContent() {
    RemoteBox(
        modifier = RemoteModifier.fillMaxSize(),
        contentAlignment = RemoteAlignment.Center,
    ) {
        RemoteText(
            text = "Hello World".rs,
            color = Color.White.rc,
        )
    }
}
GetStarted.kt

Preview your widget in Android Studio

You can preview your widget layouts directly in Android Studio's Design panel using androidx.glance.wear:wear-tooling-preview.

Predefined preview suites

The wear-tooling-preview library provides predefined PreviewParameterProvider suites to test your layouts across different container shapes and device configurations:

• Squircle Suite (SquircleAllWidgetPreviewParams): Rounded rectangle containers.
• Round Suite (RoundAllWidgetPreviewParams): Pill-shaped containers.
• Rectangular Suite (RectangularAllWidgetPreviewParams): Uncropped rectangular containers with safe padding. Images generated with this preview configuration are suitable for use as the APK-embedded preview images used by the widget picker (see Generate preview image assets).

To preview your widget in Android Studio, use @WearWidgetPreview:

@Preview
@Composable
fun HelloWidgetPreview(
    @PreviewParameter(SquircleAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}
GetStarted.kt

Create the Widget Configuration XML

Create a new file res/xml/hello_widget_info.xml to define the widget's properties and supported sizes. For a complete reference of the supported XML attributes in the <wearwidget-provider> tag, see the WearWidgetProviderInfo documentation.

<wearwidget-provider
    description="@string/hello_widget_description"
    icon="@mipmap/ic_launcher"
    label="@string/hello_widget_label"
    preferredType="SMALL">

    <container
        type="SMALL"
        previewImage="@drawable/widget_preview_small" />
    <container
        type="LARGE"
        previewImage="@drawable/widget_preview_large" />
</wearwidget-provider>
hello_widget_info.xml

Generate preview image assets

The <container> element's previewImage attribute references a drawable asset shown in the system widget picker. To generate preview assets with the correct bounds and density, use Android Studio Previews with RectangularAllWidgetPreviewParams (which generates preview variants for both small and large containers) and specify a 320 DPI smartwatch display density:

@Preview(
    name = "Widget Preview Asset",
    device = "spec:width=1000dp,height=1000dp,dpi=320",
)
@Composable
fun HelloWidgetCatalogPreview(
    @PreviewParameter(RectangularAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}
GetStarted.kt

To extract the rendered preview images, complete the following steps:

1. In Android Studio, open the Design surface for the preview composable.
2. In the preview window, right-click the rendered preview or use the preview toolbar to select Copy Image or save the image. Alternatively, use CLI tooling or automated scripts to extract Compose previews.
3. Save the small and large image files into your app's res/drawable-nodpi/ directory, such as res/drawable-nodpi/widget_preview_small.png and res/drawable-nodpi/widget_preview_large.png.

Register in AndroidManifest.xml

Register the service in your AndroidManifest.xml with the required intent filters and metadata.

<service
    android:name=".snippets.widget.HelloWidgetService"
    android:exported="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/hello_widget_label"
    android:permission="com.google.android.wearable.permission.BIND_TILE_PROVIDER">

    <intent-filter>
        <action android:name="androidx.glance.wear.action.BIND_WIDGET_PROVIDER" />
        <!-- If you already have a Tile, omit the following line. -->
        <action android:name="androidx.wear.tiles.action.BIND_TILE_PROVIDER" />
    </intent-filter>

    <meta-data
        android:name="androidx.glance.wear.widget.provider"
        android:resource="@xml/hello_widget_info" />

    <meta-data
        android:name="androidx.wear.tiles.PREVIEW"
        android:resource="@drawable/tile_preview" />
</service>
AndroidManifest.xml

Build and Deploy

After defining your service and widget, you can build your project and deploy it to a device or emulator.

Build and Install

Build the project and install the debug APK onto your connected device or emulator:

./gradlew :app:installDebug

Add and preview your widget

After the app is installed, use adb to programmatically add the widget to the carousel and display it on the screen.

Note: Wear Widgets use the underlying tile infrastructure for debugging purposes. As a result, the adb commands require the add-tile and show-tile operations.

1. Add the widget to the carousel:

adb shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SURFACE \
  --es operation add-tile \
  --ecn component <your_package_name>/.HelloWidgetService

2. Show the widget:

adb shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SYSUI \
  --es operation show-tile \
  --ei index 0